{
  id          = "0012",
  slug        = "rust-doc-authoring-pattern",
  description = "Add Documentation Authoring (Rust) section to .claude/CLAUDE.md and optional pre-commit hooks for rustdoc broken links and crate //! drift detection.",
  check       = {
    tag           = "Grep",
    pattern       = "Documentation Authoring",
    paths         = [".claude/CLAUDE.md"],
    must_be_empty = false,
  },
  instructions = "
## 1. Add to .claude/CLAUDE.md

Insert the following section under '## Key Conventions' (or equivalent conventions block).
Create .claude/CLAUDE.md if it does not exist.

### Documentation Authoring (Rust)

Three canonical doc layers — each answers a different question:

  Layer              | Where            | Answers
  -------------------|------------------|------------------------------------------
  /// on items       | handlers, types  | \"what does this item do?\"
  //! in lib.rs      | crate root       | \"what does this crate provide as a whole?\"
  node description   | .ontology/       | \"what is this concept in the architecture?\"

Rules that apply to every .rs file:

1. /// first line = one standalone sentence. No 'This function/handler/struct...' preamble.
   This line becomes the API catalog entry, describe features summary, and MCP description.
   Further lines after a blank /// are detail and do not appear in catalogs.

2. //! first sentence must be conceptually aligned with the practice node whose
   artifact_paths[0] points to this crate. Run `ontoref sync diff --docs` to verify.

3. Omit `description = \"...\"` in #[onto_api] when a /// doc comment exists above the handler.
   The proc-macro reads /// automatically. Only use explicit description = \"...\" for
   generated or macro-expanded handlers that cannot carry ///.

4. //! is mandatory on every lib.rs. Missing //! on a crate with a practice node
   fails the docs-drift pre-commit check.

Agent workflow — discovering doc state:
  ontoref describe workspace          # per-crate //! present?, coverage %, drift status
  ontoref describe features <id>      # node description + IMPLEMENTATION VIEW (//! excerpt)
  ontoref sync diff --docs            # explicit drift report before committing

Registering a new crate as a practice implementation:
  1. Add/update a Practice node in .ontology/core.ncl with artifact_paths = [\"crates/my-crate/\"]
  2. Write //! in crates/my-crate/src/lib.rs — first sentence aligned with the node description
  3. Run `ontoref sync diff --docs` to confirm Jaccard OK
  4. Run `ontoref generate-mdbook` — a docs/src/crates/my-crate.md page is generated


## 2. Add pre-commit hooks (Rust projects only)

Skip this step if the project has no Rust crates.

Add to .pre-commit-config.yaml in the local hooks section (alongside rust-clippy / rust-test):

  - id: docs-links
    name: Rustdoc broken intra-doc links
    entry: bash -c 'RUSTDOCFLAGS=\"-D rustdoc::broken-intra-doc-links -D rustdoc::private-intra-doc-links\" cargo doc --no-deps --workspace -q'
    language: system
    types: [rust]
    pass_filenames: false
    stages: [pre-commit]

  - id: docs-drift
    name: Crate //! doc drift check
    entry: bash -c 'nu -c \"use ./reflection/modules/sync.nu; sync diff --docs --fail-on-drift\"'
    language: system
    types: [rust]
    pass_filenames: false
    stages: [pre-commit]

docs-drift only fires meaningfully when the project has Practice nodes with artifact_paths
pointing to Rust crate directories. If no such nodes exist, the hook exits 0 silently.
",
}