Sync agent documentation template

[lodyai]

Summary

This branch synchronizes the repository's agent and documentation guidance with the shared Rust template so future work follows the current quality gates, Rust practices, and documentation structure.

It replaces AGENTS.md, imports docs/documentation-style-guide.md, and adds docs/contents.md plus docs/repository-layout.md. The branch also includes formatter updates to existing Markdown files caused by the required make fmt documentation gate.

No issue, roadmap task, or implementation execplan is associated with this branch.

Review walkthrough

• Start with AGENTS.md to review the superseding repository instructions and quality-gate expectations.
• Then review docs/documentation-style-guide.md for the imported documentation conventions.
• Check docs/contents.md and docs/repository-layout.md for repository-specific indexing and path guidance.
• Finish by scanning the formatter-only Markdown changes in docs/ortho-config-users-guide.md, docs/ortho-config-v0-6-0-migration-guide.md, docs/ortho-config-v0-7-0-migration-guide.md, docs/vk-design.md, docs/vk-end-to-end-testing-guide.md, and docs/execplans/adopt-ortho-config-v0-8-0.md.

Validation

• make fmt: passed after replacing the long layout table with wrapped bullets.
• make check-fmt: passed.
• make markdownlint: passed with 0 errors.
• make nixie: passed; all Mermaid diagrams validated successfully.
• make lint: passed.
• make test: passed; 293 tests passed and 1 recorded-network test was ignored.
• git diff --check: passed.
• Template conversion check: rg -n '\{[%{#]|%\}|\}\}' AGENTS.md docs/documentation-style-guide.md docs/contents.md docs/repository-layout.md || true returned no Jinja delimiters.

Notes

The GitHub connector exposed update operations but not pull request creation, so this draft PR was created with the GitHub CLI fallback.

References

• Lody session: https://lody.ai/leynos/sessions/2ea6cbad-e1bf-460e-8360-dafd072940ea

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

AGENTS.md is substantially rewritten with new engineering policies covering quality gates, abstraction workflow, Rust-specific tooling/testing/error-handling/observability rules, and project-documentation routing. Five new documentation files are added (docs/contents.md, docs/documentation-style-guide.md, docs/repository-layout.md, docs/users-guide.md, docs/developers-guide.md). Existing documentation files receive Markdown reflow and footnote formatting fixes only.

Changes

Documentation and Agent Guidance Overhaul

Layer / File(s)	Summary
AGENTS.md policy rewrite AGENTS.md	Normalises the file header; rewrites documentation-maintenance, quality-gate, commit-message, and refactoring-heuristics sections; adds abstraction/helper workflow rules; substantially rewrites the Rust-specific section (tooling targets, testing/dependency rules, structured error handling, tracing/metrics observability constraints); adds project-documentation routing, additional-tooling list, and key-takeaway text.
Documentation style guide (new file) docs/documentation-style-guide.md	Adds the complete style guide: British-English spelling/grammar/punctuation/heading/Markdown rules; canonical document-type definitions; Contents/User/Developer/Design/RFC/ADR conventions with full templates; repository-layout doc conventions; Rust API doc comment rules; diagram/image conventions; and roadmap task writing guidelines with a worked example.
New docs: contents index, repository layout, users' guide, developers' guide docs/contents.md, docs/repository-layout.md, docs/users-guide.md, docs/developers-guide.md	Adds docs/contents.md as a grouped navigation index; docs/repository-layout.md with a top-level directory tree and path-responsibility mapping; docs/users-guide.md covering installation, authentication, configuration, all core commands, and troubleshooting; docs/developers-guide.md covering normative references, build/validation workflow, test expectations, configuration development, API/command boundaries, and documentation maintenance.
Markdown reflow and footnote fixes docs/ortho-config-users-guide.md, docs/ortho-config-v0-6-0-migration-guide.md, docs/ortho-config-v0-7-0-migration-guide.md, docs/vk-design.md, docs/vk-end-to-end-testing-guide.md, docs/execplans/adopt-ortho-config-v0-8-0.md	Applies line-wrapping reflow and footnote reformatting across existing documentation files. No substantive content changes.

Possibly related PRs

• leynos/ortho-config#336: Directly overlaps — rewrites the same AGENTS.md policy sections (commit/refactoring heuristics, abstraction/port/helper policy, testing guidance, observability rules) and updates the same docs/contents.md and docs/documentation-style-guide.md files.
• leynos/agent-template-rust#37: Updates the AGENTS.md template that generates the same quality-gate, abstraction-policy, Rust-specific testing/dependency/observability sections revised in this PR.
• leynos/actix-v2a#35: Documentation-guidance-only changes touching the same set of canonical files — AGENTS.md, docs/documentation-style-guide.md, docs/contents.md, docs/developers-guide.md, and docs/repository-layout.md.

Suggested reviewers

• codescene-delta-analysis

Poem

Five new docs appeared where there once was none,
The style guide decreed: British spelling — or run! 🇬🇧
AGENTS.md tightened its quality gate,
"No commit shall pass if the tests won't validate."
With tracing and metrics now properly blessed,
The repo stood taller, thoroughly dressed. 📚✨

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Sync agent documentation template' accurately describes the main changes: synchronising AGENTS.md and importing documentation guidance from a shared template.
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	This PR contains only documentation changes (Markdown files). No functionality, behavioural changes, or code modifications were introduced, so test coverage requirements do not apply.
User-Facing Documentation	✅ Passed	This PR is purely a documentation and guidance synchronisation with no user-facing feature or behavioural changes. The users-guide.md comprehensively documents existing vk functionality (installati...
Developer Documentation	✅ Passed	PR adds comprehensive developer documentation in docs/developers-guide.md covering build workflow, API/command boundaries, test expectations, and architecture references. No new APIs or code change...
Module-Level Documentation	✅ Passed	PR contains only documentation and guidance files (.md); no code modules (.rs/.py/.ts) were added or modified, so the module-level documentation check is not applicable.
Testing (Unit And Behavioural)	✅ Passed	Pull request contains only documentation and Markdown formatting changes; no code changes, functional behaviour additions, or bug fixes present. Testing requirement does not apply to documentation-...
Testing (Property / Proof)	✅ Passed	This PR introduces only documentation changes (AGENTS.md updates, new docs files, and Markdown formatter updates). No code logic, algorithms, or invariants are introduced, making the property/proof...
Testing (Compile-Time / Ui)	✅ Passed	This PR contains only documentation, policy guidance, and Markdown formatting updates; no compile-time behaviour or UI output code is introduced, making the testing check inapplicable.
Unit Architecture	✅ Passed	PR modifies only 12 Markdown documentation files (AGENTS.md, docs/*.md). The Unit Architecture check assesses code organisation, separation of concerns, and test architecture—concepts that do not a...
Domain Architecture	✅ Passed	The PR updates AGENTS.md with explicit domain architecture guidance (semantic error enums, opaque errors at app boundary, feature-grouped structure) that enforces proper segregation between domain...
Observability	✅ Passed	This PR synchronises documentation and guidance, not operational code. The existing codebase already has tracing instrumentation initialised in main.rs with debug/warn/error macros at meaningful de...
Security And Privacy	✅ Passed	Documentation and guidance files contain no secrets, hardcoded credentials, or unsafe authentication patterns. All credential examples use placeholders; error handling guidance prohibits exposing s...
Performance And Resource Use	✅ Passed	PR contains only documentation and instruction changes; no code, algorithms, data structures, I/O, allocations, or performance-critical paths were modified.
Concurrency And State	✅ Passed	PR contains only documentation and guidance changes (AGENTS.md, docs/*.md files, and Markdown formatter updates). No functional code changes involving concurrency, shared state, async execution, lo...
Architectural Complexity And Maintainability	✅ Passed	This is a documentation-only PR with no code changes. It updates AGENTS.md guidance and adds documentation files (docs/contents.md, docs/documentation-style-guide.md, docs/repository-layout.md, etc...
Rust Compiler Lint Integrity	✅ Passed	This PR modifies only documentation files (.md) and agent instructions (AGENTS.md); no Rust source code (.rs) changes are present, making the Rust lint integrity check inapplicable.
Description check	✅ Passed	The PR description comprehensively describes the changeset, covering the replacement of AGENTS.md, imports of documentation-style-guide.md, and addition of new documentation files with detailed validation results.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 feat/sync-agent-docs

---

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

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 2500000 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: f35678f673

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

[leynos]

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

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/documentation-style-guide.md`:
- Around line 69-80: The minimal canonical set of documentation files is
incomplete because it omits the documentation-style-guide.md file, which is an
important long-lived reference. Add documentation-style-guide to the
brace-expanded list of canonical filenames in the section describing the minimal
canonical set, so that it includes contents, users-guide, developers-guide,
repository-layout, and documentation-style-guide among the core documentation
files that should exist in docs/.
- Around line 537-538: Update the documentation style guide section at lines
537-538 that currently mandates marking all `# Examples` code blocks with
`no_run`. Replace the blanket requirement with guidance that reserves `no_run`
only for examples that genuinely cannot execute (such as those requiring
external resources, incomplete snippets, or environment-specific setup). Clarify
that examples which can execute should be allowed to run as doctests so the
compiler can verify they compile and execute correctly, making the `no_run`
marker context-dependent rather than universally applied to all API
documentation examples.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ea574256-487b-4f8a-baa8-cf2317995c17

📥 Commits

Reviewing files that changed from the base of the PR and between 26495c3 and 29b5c85.

📒 Files selected for processing (12)

• AGENTS.md
• docs/contents.md
• docs/developers-guide.md
• docs/documentation-style-guide.md
• docs/execplans/adopt-ortho-config-v0-8-0.md
• docs/ortho-config-users-guide.md
• docs/ortho-config-v0-6-0-migration-guide.md
• docs/ortho-config-v0-7-0-migration-guide.md
• docs/repository-layout.md
• docs/users-guide.md
• docs/vk-design.md
• docs/vk-end-to-end-testing-guide.md