Correct users-guide JSON/config claims and document glob

[lodyai]

Summary

Assessment of docs/users-guide.md against the currently implemented codebase
found the guide broadly accurate, but surfaced one substantive accuracy error
and a few smaller gaps. This PR corrects them and strengthens example coverage.

Guide fixes (docs/users-guide.md)

• JSON failure stream (the substantive error). In JSON mode a successful
  command writes a result document to stdout, but a failure writes the
  diagnostic document to stderr with stdout left empty. The guide claimed
  the diagnostic went to stdout. Corrected both the "Control output and
  accessibility" and "JSON output" sections, and relabelled the sample envelope
  as the diagnostic document written to stderr. Matches runner/dispatch.rs
  (result → stdout) vs diagnostic_json.rs (diagnostic → stderr) and the
  existing json_diagnostic_example_matches_live_schema test.
• Documented glob(pattern), which was registered (manifest/mod.rs) but
  undocumented, even though the README advertises globbing. Added a subsection
  covering its pairing with foreach and its matching semantics.
• --jobs value name aligned with the CLI: <N> (accepts 1 to 64) rather
  than <1..64>.
• Config precedence clarified: system/user configuration are discovered from
  XDG/home conventions rather than two separately named Netsuke layers.

Test coverage

guide-command-available-manifest was previously only compiled via generate,
never asserting which when/command_available branch was selected. Added a
unix e2e test (command_available_selects_the_documented_action_branch) that
pins both branches deterministically by isolating PATH — a stub cargo-nextest
present vs absent — and asserts the resulting action command
(cargo nextest run vs cargo test).

Follow-up

Issue #443 tracks a dedicated, comprehensive docs/stdlib-yaml-and-jinja-guide.md
with executable examples for the full template standard library (path/hash/time/
fetch/shell/grep/file tests), linked from the user's guide and README.

Quality gates

check-fmt, markdownlint (+ en-GB-oxendict spelling), lint (clippy + Whitaker
dylint), and full make test all pass locally with zero failures.

References

• Lody session: https://lody.ai/leynos/sessions/cc30cdc2-3670-483b-8ba7-7e508403382f
• Follow-up issue: Document the template standard library in a dedicated stdlib guide with executable examples #443

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Walkthrough

The user guide documents glob expansion, command-line limits, configuration discovery, and JSON stream behaviour. End-to-end tests validate manifest action selection when cargo-nextest is available or absent.

Changes

Guide and documentation examples

Layer / File(s)	Summary
Document globbing and runtime options docs/users-guide.md	Document glob(pattern) expansion, wildcard semantics, the 1–64 --jobs range, and platform-based configuration discovery.
Document JSON output streams docs/users-guide.md	Specify versioned success documents on stdout, diagnostic documents on stderr, and generated content embedded in result.content.
Validate documented command selection tests/documentation_examples_e2e_tests.rs	Use an isolated PATH to verify that manifest generation selects the cargo nextest run or cargo test branch according to command availability.

Possibly related PRs

• leynos/netsuke#427: Extends the documentation-example E2E harness used by this test.
• leynos/netsuke#447: Overlaps with the isolated PATH and command-selection validation.

Suggested labels: Issue

Suggested reviewers: leynos, codescene-access

Poem

Glob stars bloom through files,
JSON streams find their course,
Nextest waits—or tests arise,
Docs and checks march in one source.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	The new e2e test isolates PATH, stubs cargo-nextest, and asserts both present/absent branches in the generated manifest, so it would fail under inverted or constant implementations.
User-Facing Documentation	✅ Passed	PASS: docs/users-guide.md covers the new glob() helper, JSON stream semantics, config discovery, and --jobs; no sibling locale guide needs syncing.
Developer Documentation	✅ Passed	Only user-guide text and tests changed; no internal APIs, architecture, ADRs, roadmap items, or locale docs were added or altered.
Module-Level Documentation	✅ Passed	tests/documentation_examples_e2e_tests.rs and the related helper module both carry module docstrings; no new undocumented module was introduced.
Testing (Unit And Behavioural)	✅ Passed	PASS: The unit tests cover command_available branches with a mocked Jinja env, and the e2e test runs the built netsuke binary with an isolated PATH, exercising the real CLI boundary.
Testing (Property / Proof)	✅ Passed	The patch is docs plus a two-branch e2e regression; it adds no new broad invariant or proof obligation, and existing tests already cover glob and command_available edge cases.
Testing (Compile-Time / Ui)	✅ Passed	No compile-time Rust/TS behaviour changed; the new e2e test is runtime-only and the diff adds no snapshot surface requiring trybuild or Insta.
Unit Architecture	✅ Passed	PASS: the new e2e helper isolates PATH explicitly and returns Result, and command_available already uses an injected resolver; no hidden writes or ambient dependencies were added.
Domain Architecture	✅ Passed	PASS: The patch only changes docs and integration tests; no domain model, repository, transport, or persistence code was altered.
Observability	✅ Passed	Only docs and tests changed; no runtime behaviour, logging, metrics, tracing, or alerts were introduced or altered.
Security And Privacy	✅ Passed	PASS: this change only updates docs and adds deterministic fake PATH stubs; it exposes no secrets, auth gaps, or sensitive data.
Performance And Resource Use	✅ Passed	PASS: The PR is docs-plus-test only; the new helper performs two bounded manifest generations with isolated PATH and no unbounded loops, batching, or repeated I/O.
Concurrency And State	✅ Passed	No shared mutable state or async concurrency was introduced; the new test isolates PATH via env_clear and temp workspaces.
Architectural Complexity And Maintainability	✅ Passed	PASS: The PR adds only a small private test helper plus one test, reusing existing test utilities; no new layers, traits, registries, or dependencies were introduced.
Rust Compiler Lint Integrity	✅ Passed	PASS: The touched Rust test adds a used helper and test; no new lint suppressions or .clone() calls appear in the diff, and imports resolve to real uses.
Title check	✅ Passed	The title clearly matches the PR’s documentation fixes and test coverage for users-guide JSON, config, and glob behaviour.
Description check	✅ Passed	The description is directly about the same guide corrections and e2e test additions made in this changeset.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch final-0-1-0-docs-audit

---

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

[sourcery-ai]

Sorry @leynos, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f17507adb2

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codescene-access]

No quality gates enabled for this code.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.

[buzzybee-df12]

@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.

[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.

[leynos]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.