fix(zcode): bound default bootstrap file reads

[luvs01]

Summary

Use the shared bounded regular-file reader for ZCode's default bootstrap lookup, matching the injected integration path.

• Refuse files above 4 MiB, final symlinks, and special files while preserving normal relocation, missing-file defaults, and explicit ZCODE_DATA_DIR overrides.
• Reuse the existing reader rather than duplicating relocation or ownership logic, and add real-file boundary regressions.

This is a stacked child of #723, targeting codex/split719-bounded-reader-20261012. Its reader dependency must land first; this is not an independent patch against upstream dev.

Verification

Current head: a3c6bc7cbc0975e861cfae9d09a556298d0e8c98.

• Current-head aggregate CI passed.
• Relevant regression coverage is in tests/providers/zcode-client.test.ts.
• Implementation-stage local validation used focused tests. A full local repository run was not repeated across the parallel candidate worktrees; completed hosted CI supplies broader evidence.
• Review-thread inspection found no unresolved findings or outstanding change requests. Parent landing and any subsequent retargeting require their own current-head checks.

Checklist

• The parent dependency and submission order are explicit.
• Regression coverage and current-head CI evidence are recorded.
• Integration documentation is updated.

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Summary by CodeRabbit

• Bug Fixes
  • ZCode now accepts bootstrap settings only from regular files no larger than 4 MiB. Symbolic links, special files, and oversized files are rejected, and the default data root is used only when the settings file is missing.
  • You can still choose a data root explicitly with ZCODE_DATA_DIR, bypassing bootstrap discovery.
• Documentation
  • Clarified the bootstrap-file requirements and how to select a data root explicitly.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: luvs01/opencodex/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 88fcf6d2-c0c9-4250-966e-a45391258947

📥 Commits

Reviewing files that changed from the base of the PR and between 241186b and a3c6bc7.

📒 Files selected for processing (4)

• docs-site/src/content/docs/guides/integrations.md
• src/clients/config-export.ts
• structure/clients/integrations.md
• tests/providers/zcode-client.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

ZCode bootstrap reads now use the shared file I/O adapter. Bootstrap path lookup rejects symlinks, special files, and files larger than 4 MiB. Tests and documentation describe the lookup behavior and recovery options.

Changes: ZCode bootstrap lookup

Layer / File(s)	Summary
Delegate bootstrap reads to shared file I/O src/clients/config-export.ts	The ZCode path I/O adapter delegates reads to fileIO().readText(path).
Specify and test bootstrap path lookup structure/clients/integrations.md, tests/providers/zcode-client.test.ts, docs-site/src/content/docs/guides/integrations.md	Bootstrap lookup uses a bounded regular-file reader. Tests cover the 4 MiB boundary, invalid file types, missing settings, relocation, and the explicit ZCODE_DATA_DIR override. Documentation describes the file requirements and recovery options.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: lidge-jun, ingwannu

Merge Risk: ⚪ Minimal · up to a3c6b

No actionable merge-blocking issue is established. The bootstrap-file change appears ready for normal merge checks, subject to landing its parent dependency.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: limiting default ZCode bootstrap file reads.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[luvs01]

No description provided.

[luvs01]

No description provided.

[luvs01]

Author follow-up for HEAD c25a70ba9b2b0369a42a2af9e4bc2ce5d36772db: refresh the stacked parent and rerun the child checks before carrying forward the latest #723 validation.

The body says the updated parent head is included, but #723 is now at 241186b190def799b004fc29202bfa1f550d656c. The commit comparison reports this child 2 commits ahead and 37 behind, with merge base 00ede585e55a17ecdccb88a1900e25a91651aef7. In particular, the parent's bounded-reader allocation changes (c0e9e45e542b9e292160568648971362935c53b8 and 1f01b570cda64c51f0e0312f0f030d2a8959ec38) and their growth/shrink/overflow regressions are not included in this child head.

Please integrate the updated parent while preserving this PR's ZCode changes, rerun bun run typecheck, bun run structure:check, the recorded ZCode/bounded-reader/aside/layout test command, and git diff --check on the resulting parent-relative delta. Then update the body with the exact parent and child SHAs and results. The existing 70-pass/2-skip result remains evidence for the recorded old head; it does not validate the refreshed combination. This is a stack synchronization and verification gap, not a newly demonstrated ZCode runtime defect.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T04:03:18.536071Z	a3c6bc7	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[luvs01]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[luvs01]

Closing as already integrated in development commit a29cb3d8b88279b806af2f50cf86676d0559b49a.

Compared the four changed files at this PR's current head a3c6bc7cbc0975e861cfae9d09a556298d0e8c98 with that landed commit. The user guide is identical; the bounded bootstrap-reader implementation is preserved with an explanatory comment; the structure text clarifies missing/valid-settings fallback versus failed reads; and the regression cases are retained with an additional Windows symlink-capability probe. No unique change from this PR remains to be carried.

This is a content-inclusion check, not a new test run. The source branch is retained.