Import the revised Whitaker user's guide

[leynos]

Summary

This branch refreshes docs/whitaker-users-guide.md from the
upstream leynos/whitaker user's guide, which is the sanctioned way to
update that file: the developers' guide records it as a near-verbatim
import to be refreshed from the upstream URL rather than edited in
place (docs/developers-guide.md).

The guide had drifted from upstream and was carrying advice that no
longer holds. The corrections matter beyond prose accuracy, because
this file is what a contributor consults when the Whitaker gate fails:

• no_std_fs_operations in-source attributes. The old text claimed
  an item-level #[allow] works "since the lint honours Rust's
  lint-level attributes". It does not — the lint emits through
  LintContext::emit_span_lint, which resolves the level at the
  visitor's current lint node rather than at the node owning the
  offending code (guide, lines 777-785;
  upstream leynos/whitaker#270, still open). The guide now states the
  real position and directs the reader to excluded_paths, and records
  that a malformed entry — notably a trailing separator, which would
  otherwise collapse to the crate root and disable the lint crate-wide —
  is discarded rather than repaired.
• Installer behaviour. The guide gains --suite-version pinning and
  the source build it forces (guide, line 110),
  --no-source-fallback with the suite-source= marker
  (guide, line 208), the Rust 1.85 requirement
  for the published installer crate (guide, line 19), and
  the GLIBC_2.35 floor for the published Linux artefacts
  (guide, line 24).
• The shipped agent skill (guide, line 898).

Relative links are rewritten to absolute URLs, as the task required.
This is a real defect rather than a cosmetic one: the imported file sits
beside unrelated docs/, so a bare developers-guide.md resolves to
this repository's own developer's guide, and
../skills/addressing-whitaker-findings/SKILL.md resolves outside
docs/ to a path that does not exist here at all. Four targets are
rewritten and carried in a link-definition block at the end of the file
(guide, lines 942-950), which keeps the
prose rewrappable by mdtablefix.

The three "Netsuke deviation from upstream" callouts are preserved and
re-homed to the sections they guard: the Cargo-metadata pinning note now
follows the renamed "Version pinning through Cargo metadata" section
(guide, line 170), the lint-selection note
follows "Selecting individual lints" (guide, line
269), and a third covers the new agent-skills
section (guide, line 933). The newer
--suite-version text needed one sentence distinguishing it from the
metadata pin: it is a one-off installation choice, where the metadata
block takes over library resolution for every Dylint invocation. Netsuke
takes neither, and the standing decision is unchanged.

No issue, roadmap task, or execplan covers this work; it was requested
directly as a documentation import.

Review walkthrough

• Start with docs/whitaker-users-guide.md as a whole, comparing
  against the upstream source it was imported from. The diff is large
  because the upstream file gained roughly a hundred lines, but the
  portions that are new to this repository rather than to upstream are
  precisely the three callouts and the trailing link-definition block.
• Then check the link rewrites at
  lines 942-950, against the two original relative forms
  at line 7 and line 869 as they stood before this
  branch.
• Finally read the two re-homed callouts
  (line 170, line 269)
  and confirm the deviation they describe is still the repository's
  policy. The supporting evidence is in
  tests/whitaker_boundary_contract.rs and the
  "Quality gates" section of docs/developers-guide.md;
  the installer pin lives at
  .github/workflows/ci.yml, line 226.

Validation

Gates were run sequentially over the working tree by the scrutineer
sub-agent, with each gate's output captured to a log under /tmp.
The diff is documentation-only, so make test was deliberately not run;
the reasoning is recorded in the notes below.

• make check-fmt: pass — mdtablefix --check reports "141 files left
  unchanged"; cargo fmt --check and ruff format --check clean.
  Log: /tmp/check-fmt-netsuke-import-updated-whitaker-guide.out
• make markdownlint (includes make spelling): pass — typos-config-builder gate exited 0 with no diff, markdownlint-cli2 reported "Linting: 141
  file(s) / Summary: 0 error(s)".
  Log: /tmp/markdownlint-netsuke-import-updated-whitaker-guide.out
• make nixie: pass — "All diagrams validated successfully!".
  Log: /tmp/nixie-netsuke-import-updated-whitaker-guide.out
• make lint: pass — rustdoc, Clippy, Whitaker over both packages,
  lint-python, yamllint, and actionlint all completed with exit 0
  and no error or warning lines.
  Log: /tmp/lint-netsuke-import-updated-whitaker-guide.out
• make typecheck: pass — ty check "All checks passed!";
  cargo check --all-targets --all-features under -D warnings finished.
  Log: /tmp/typecheck-netsuke-import-updated-whitaker-guide.out

Before the diff was committed, the file was canonicalised with the same
mdtablefix rule set that check-fmt enforces
(--wrap --renumber --breaks --ellipsis --fences), scoped to the one
file rather than running make fmt.

Notes

• make test was not run, deliberately. No Rust test reads this
  file. The tested-example fence machinery covers README.md,
  docs/users-guide.md, and docs/stdlib-yaml-and-jinja-guide.md; the
  new fences here are plain sh and text blocks with no consumer. The
  only non-documentation references to the guide are a comment in
  dylint.toml and a rustdoc comment in whitaker_boundary_contract.rs,
  and that test binary was compiled and run in anger under
  make lint's --all-targets Clippy and Whitaker passes.
• Two lines of the upstream import were rewrapped by mdtablefix,
  in the ra_ap_syntax runbook sentence and the agent-skills closing
  sentence. This is a consequence of the link rewrites changing those
  lines' lengths, not an unrelated reformat.
• The deviation callouts are not wholesale additions. Two existed
  before this branch and were moved to track the upstream text they
  qualify; only the third, covering agent skills, is new.
• The re-homed excluded_paths guidance did not require a change to
  dylint.toml. The upstream correction says in-source attributes do
  not suppress the lint, which is what this repository already does in
  practice: every exemption in dylint.toml is an excluded_paths or
  excluded_crates entry, and no in-source suppression is used.

References

• Lody session:
  https://lody.ai/leynos/sessions/94a3fd45-394b-4cb7-be01-b570adadfeee

Summary by Sourcery

Refresh the Whitaker user guide from upstream and align its guidance and links with current installer and lint behavior.

New Features:

• Add guidance for suite-version pinning, source-build fallback control, installer compatibility requirements, and the shipped Whitaker agent skill.

Bug Fixes:

• Correct the documented behavior of no_std_fs_operations suppressions and malformed excluded_paths entries.
• Replace broken repository-relative documentation links with absolute upstream links.

Enhancements:

• Refresh the Whitaker user guide from upstream while preserving and relocating Netsuke-specific policy deviations.

Documentation:

• Update Whitaker installation, version-pinning, lint-selection, suppression, and agent-skill documentation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[sourcery-ai]

Reviewer's Guide

Refreshes the Whitaker user guide as a near-verbatim upstream import, adding current installer, lint suppression, and agent-skill guidance while preserving Netsuke deviations and fixing links that would otherwise resolve incorrectly in this repository. Documentation formatting, linting, and typechecking gates pass.

Flow diagram for Whitaker installer source selection

flowchart LR
    A["whitaker-installer"] --> B{"Suite version pinned?"}
    B -->|"yes"| C["Build suite from source"]
    B -->|"no"| D{"Published artefact available?"}
    D -->|"yes"| E["Use prebuilt artefact"]
    D -->|"no"| F{"--no-source-fallback"}
    F -->|"enabled"| G["Fail with fallback error"]
    F -->|"disabled"| C
    C --> H["Print suite-source=source"]
    E --> I["Print suite-source=prebuilt"]

Loading

Flow diagram for Whitaker lint suppression guidance

flowchart TD
    A["no_std_fs_operations diagnostic"] --> B{"In-source #[allow] or #[expect]?"}
    B -->|"does not suppress lint"| C["Diagnostic remains"]
    B -->|"use excluded_paths"| D{"Path entry well formed?"}
    D -->|"yes"| E["Narrow module-scoped exemption"]
    D -->|"no"| F["Discard entry and log warning"]
    F --> G["Avoid trailing separator that broadens scope"]

Loading

File-Level Changes

Change	Details	Files
Refresh the Whitaker user guide from upstream while preserving Netsuke-specific policy callouts.	Import upstream installer, lint-configuration, and agent-skills guidance. Correct no_std_fs_operations suppression and malformed excluded_paths behavior. Re-home the three Netsuke deviation notes alongside the upstream sections they qualify. Rewrite repository-relative links as upstream absolute URLs and add link definitions.	docs/whitaker-users-guide.md
Clarify installer reproducibility and artifact-selection behavior.	Document suite revision pinning, its forced source build, and distinction from Cargo metadata pinning. Document --no-source-fallback, its environment-variable equivalent, incompatibilities, and suite-source= output. Document the published installer Rust MSRV and Linux GLIBC baseline.	docs/whitaker-users-guide.md
Validate and canonicalize the documentation-only import against repository quality gates.	Canonicalize Markdown wrapping and link-definition formatting with the repository's mdtablefix rules. Run formatting, Markdown/spelling, diagram, lint, and typecheck gates successfully; omit tests because the changed document has no test consumer.	docs/whitaker-users-guide.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.