[osvaldomcc]

Description

• Add a job step to the framework distribution workflow that builds the User Guide as Markdown with sphinx-markdown-builder and embeds it into system/Docs, so coding agents get version-matched documentation alongside the distributed framework.
• Ship �dmin/framework/AGENTS.md to the appstarter repository root on release, pointing agents to the embedded docs.

No framework runtime code is touched; changes are limited to GitHub Actions workflow, the deploy script, and Sphinx build requirements.

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication) — no PHP code changed
• Unit testing, with >80% coverage — no PHP code changed; covered by the workflow's est -f ./source/system/Docs/index.md verification step
• User guide updated — no public API/behavior change; CI and release tooling only
• Conforms to style guide

[michalsn]

Thanks for the PR. I don't see a clear benefit to shipping the entire User Guide with every framework installation. Could you clarify:

• How much does this increase the package and download size?
• Why convert to Markdown instead of distributing the existing RST sources?
• What concrete problem does this solve for coding agents?

My take is that AGENTS.md shouldn't be included in every appstarter project. Application owners should decide which instructions apply to agents working on their projects.

[osvaldomcc]

Hi Michal 1. Size Measured from the 4.8 sources: - Markdown payload: ~2.2 MB uncompressed (248 RST pages + inlined code samples; `_static/*`, `images/*`, `changelogs/*` excluded). - The `codeigniter4/framework` tree is ~3.9 MB, so ≈ +56% uncompressed; text compresses ~3-4x, so roughly +0.5-0.7 MB on the download. I won't pretend that's free — and unlike Next.js (141 MB package) the ratio is not negligible for us. That's also why I'd pair it with the same escape hatch they use (see #4). 2. Why Markdown instead of the RST sources? Same reason Next.js ships plain Markdown and not their source format: raw RST only makes sense through Sphinx — directives, roles and `:doc:` refs resolve at build time. Handed to an agent as-is it's directive noise plus broken includes. Markdown is build-free, greppable, and read natively. It's a mechanical transform of the existing sources, so there is no second source of truth to maintain. 3. Concrete problem for agents Version matching. Without it, agents either pull the *latest* online guide (mismatched with the pinned 4.x) or fall back on training data. Bundling the guide means the agent reads the exact API surface of the installed release, offline, no network, no toolchain. Next.js measured precisely this gap, which is why they ship docs with the package. 4. AGENTS.md Fair point that owners should decide — and Next.js solves it the same way I propose: it's a default, not a mandate. Concretely: - opt-out available (`--no-agents-md` in their case; I can omit the step for appstarter or make it a documented flag), and - the shipped file is a short pointer to the version-matched docs, with a clearly delimited managed block so owners add their own instructions outside it (or delete it), exactly like Next.js's managed markers. So: default-on for the good out-of-the-box agent experience, trivially overridable by any app owner. Happy to match that opt-out if you want it. El dom, 18 oct 2026 a las 5:24, Michal Sniatala ***@***.***>) escribió:

…

***@***.**** commented on this pull request. Thanks for the PR. I don't see a clear benefit to shipping the entire User Guide with every framework installation. Could you clarify: - How much does this increase the package and download size? - Why convert to Markdown instead of distributing the existing RST sources? - What concrete problem does this solve for coding agents? My take is that AGENTS.md shouldn't be included in every appstarter project. Application owners should decide which instructions apply to agents working on their projects. — Reply to this email directly, view it on GitHub <#10638?email_source=notifications&email_token=AQVKQYXGJPAQIGEJFAILIBL5USD6FA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJWGIZTGMBWGM32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#pullrequestreview-5562330637>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQVKQYXCRINVYN25VOTTWPT5USD6FAVCNFSNUABEKJSXA33TNF2G64TZHM2DCNBWGM4DQNR3JFZXG5LFHM2TQNZQG4YTKMRQGCQXMAQ> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AQVKQYTRDYN4NCPVVAMFEXD5USD6FA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJWGIZTGMBWGM32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/AQVKQYU7XKLHRJTN32A2WLT5USD6FA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTKNJWGIZTGMBWGM32M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[michalsn]

Thanks for clarifying. I understand the value of version-matched documentation, and the size measurements help. The Next.js results are encouraging, but I'd like to see examples of CodeIgniter tasks where bundled documentation improves the outcome enough to justify including it by default.

I would prefer an opt-in way to install the matching docs and agent instructions. Omitting AGENTS.md doesn't address the package-size concern, since the documentation would still be installed for everyone.

I would also like to hear what other maintainers think about this before we decide on it.

[osvaldomcc]

Ok, thank you for letting me know

…

On Mon, Oct 19, 2026, 2:01 PM Michal Sniatala ***@***.***> wrote: *michalsn* left a comment (codeigniter4/CodeIgniter4#10638) <#10638 (comment)> Thanks for clarifying. I understand the value of version-matched documentation, and the size measurements help. The Next.js results are encouraging, but I'd like to see examples of CodeIgniter tasks where bundled documentation improves the outcome enough to justify including it by default. I would prefer an opt-in way to install the matching docs and agent instructions. Omitting AGENTS.md doesn't address the package-size concern, since the documentation would still be installed for everyone. I would also like to hear what other maintainers think about this before we decide on it. — Reply to this email directly, view it on GitHub <#10638?email_source=notifications&email_token=AQVKQYU7NA4BKW24PTELU6L5UZJHFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMRXGM3TSNBSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-6273794281>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQVKQYUA24Z7TOEIV4LL57L5UZJHFAVCNFSNUABEKJSXA33TNF2G64TZHM2DCNBWGM4DQNR3JFZXG5LFHM2TQNZQG4YTKMRQGCQXMAQ> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AQVKQYQUV6UHF4MFABFFPF35UZJHFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMRXGM3TSNBSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2KUZTPN52GK4S7NFXXG> and Android <https://github.com/notifications/mobile/android/AQVKQYRP6X7LSBG6VHYOEJL5UZJHFA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTMMRXGM3TSNBSHAY2M4TFMFZW63VGMF2XI2DPOKSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA>. Download it today! You are receiving this because you authored the thread.Message ID: ***@***.***>

[paulbalandan]

Thanks for the figures, but I would agree with @michalsn to bundling the docs opt-in. In #10133, it was discussed moving the user guide to Markdown using codeigniter4/docs-update. Once that happens, the versioned docs for agents can come for free as the markdown artifacts are already there.

Issues I'm seeing here:

• An RST-to-Markdown conversion every build is like converting blindly given the issues with php-domain directives. An example output of conversion on PHP-heavy docs would be nice.
• Adding the step before the deploy step risks blocking a release on a failed docs build.
• The wording of AGENTS.md is strongly worded that implies every version has BC breaks. A patch release should not have compatibility breaks.
• The placement in system/Docs which only appears in releases but not at source does not sit well with me.

If any, completing the docs migration would be a better path.