Skip to content

feat: embed agent-ready docs and AGENTS.md in framework distributions - #10637

Closed
osvaldomcc wants to merge 2 commits into
codeigniter4:4.8from
osvaldomcc:new/agents-md-distribution
Closed

osvaldomcc wants to merge 2 commits into
codeigniter4:4.8from
osvaldomcc:new/agents-md-distribution

Conversation

@osvaldomcc

Copy link
Copy Markdown

Make the CodeIgniter 4 distribution friendlier to AI coding agents (Codex,
Claude Code, Cursor, Copilot, etc.) by shipping managed agent instructions and
version-matched documentation in the artifacts end users download, following
the same AGENTS.md convention adopted by other frameworks.

1. Ship AGENTS.md in both distributable repos

  • Add admin/framework/AGENTS.md with managed agent instructions that direct
    agents to the bundled documentation (system/Docs for the framework
    distribution, vendor/codeigniter4/framework/system/Docs for Composer /
    app starter installs).
  • Extend .github/scripts/deploy-appstarter to copy the same canonical file
    into the app starter root, so a single source serves both install channels
    (manual zip download and composer create-project).

2. Embed the user guide as Markdown in system/Docs

  • The framework release job in deploy-distributables.yml now converts the
    Sphinx user guide to Markdown with sphinx-markdown-builder and embeds it
    into system/Docs before the distribution is assembled.
  • _static, changelogs and images are excluded from this build (the
    output is LLM-oriented); the HTML user guide build is unaffected since the
    exclusions are passed only to the Markdown invocation via -D.
  • A test -f system/Docs/index.md guard fails the job if the conversion
    produces no output, so a release can never ship without its embedded docs.

No framework runtime code is touched: no BC impact and nothing applicable for
PHP unit tests or PHPDoc (CI/distribution changes only). Docs ship inside the
release tag, so agents always get documentation matching the installed
framework version.

Add admin/framework/AGENTS.md so the framework distribution includes
managed agent instructions pointing at system/Docs, and copy the same
file into the appstarter root during deploy so both install channels
(zip and Composer) get it.
Convert the Sphinx user guide to Markdown in the framework release job
(excluding _static, changelogs and images) and embed it in system/Docs
before the distribution is assembled, giving agents version-matched
docs for both manual downloads and Composer installs.
@carson-codeigniter4 carson-codeigniter4 Bot added 4.8 PRs that target the `4.8` branch. github_actions Pull requests that update Github_actions code needs template Opened issues not following the bug form template labels Oct 14, 2026
@carson-codeigniter4

Copy link
Copy Markdown

Hi there, @osvaldomcc! 👋

It looks like this pull request does not follow our template:

Please update the description to follow the template. The needs template label will be removed automatically once it does.


Hi there, @osvaldomcc! 👋

Thank you for sending this PR!

We expect the following in all Pull Requests (PRs).

Important

We expect all code changes or bug-fixes to be accompanied by one or more tests added to our test suite to prove the code works.

If pull requests do not comply with the above, they will likely be closed. Since we are a team of volunteers, we don't have any more time to work
on the framework than you do. Please make it as painless for your contributions to be included as possible.

See https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md

@osvaldomcc osvaldomcc closed this by deleting the head repository Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

4.8 PRs that target the `4.8` branch. github_actions Pull requests that update Github_actions code needs template Opened issues not following the bug form template

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants