docs: add plain Wesley onboarding path

[flyingrobots]

Summary

Closes #678.

Stacked on #685. This PR's original slice is the Plain Wesley onboarding/docs issue. During stack landing, already-merged descendant slices are now present in the branch diff until #686 is merged downward.

Why

The docs needed a first-hour path that explains Wesley in standard GraphQL terms before introducing advanced assurance vocabulary. This reduces onboarding friction while preserving the domain-empty compiler boundary.

Changes

• Adds docs/topics/plain-wesley.md as a first-hour compiler path using standard GraphQL and generated-artifact language.
• Adds a GraphQL-to-Wesley term map, beginner tutorial, and contributor tutorial.
• Corrects the tutorial IR inspection step so it expects version and types, not unset metadata.
• Routes the new page from docs/GUIDE.md, the docs front door, docs orientation, and the topics map.
• Adds a public-vocabulary rule requiring plain-English aliases or internal/experimental markings for new public nouns.
• Adds the new topic to the docs truth manifest and changelog.
• Follow-up CodeRabbit fixes in the stacked diff tighten external target command path safety, align docs-maintenance vocabulary policy, reuse xtask command labels, and share GraphQL argument extraction.

Method Evidence

• Onboarding review-thread fix is in cf0730e5.
• Additional review cleanup commits: 55acf17b, 0856f2b7, 70878ba9, 84134ff0.
• The tutorial was checked against an actual wesley schema lower --json run.
• The new page stays on generic compiler facts and avoids target/runtime semantics.
• The external-target path rule now rejects absolute paths, .. traversal, symlink escapes, and canonicalization escapes before launch.

Tracker Hygiene

• Closes Docs: add plain Wesley onboarding path #678.
• No follow-up issue required for the resolved review corrections.

Risk

Low to medium. Most changes are documentation-only; one stacked cleanup refactors shared argument extraction and is covered by wesley-core integration tests plus full preflight.

Backout

Revert this PR, or revert individual follow-up commits if one cleanup needs to be separated from the onboarding slice.

Testing

• RED: docs assertion failed while docs/topics/plain-wesley.md still claimed metadata as an expected top-level key.
• GREEN: same assertion passes after removing metadata.
• Actual CLI check: wesley schema lower --json output includes version and types and omits metadata for the tutorial schema.
• pnpm exec prettier --check docs/topics/plain-wesley.md
• cargo xtask docs-check
• cargo test -p wesley-core --test lowering_validation -- --nocapture
• cargo test -p wesley-core --test operation_analysis -- --nocapture
• cargo test -p xtask
• cargo clippy -p wesley-core --all-targets -- -D warnings
• git diff --check
• pnpm run preflight
• pre-push Rust product preflight

Checklist

• Documentation updated.
• Review-thread fixes pushed.
• Local validation passed.
• PR remains non-draft.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR enforces duplicate non-repeatable directive rejection during SDL lowering while preserving arrays for repeatable directives, adds extensive documentation (Plain Wesley onboarding, Assurance Capability Matrix, External Target Protocol MVP, security tooling policy, first-PR contributor path), and introduces cargo xtask bench-ir, replacing the retired pnpm perf:ir workflow in design docs.

Changes

SDL Directive Repeatability Lowering

Layer / File(s)	Summary
Repeatable directive detection crates/wesley-core/src/adapters/apollo.rs	Computes repeatable directive names from the SDL document and introduces TypeBuildAccumulator for merging type definitions/extensions.
Extension merge and insertion semantics crates/wesley-core/src/adapters/apollo.rs	Adds extract_directives_with_repeatability, repeatable_directive_names_from_document, and a fallible insert_directive_value that errors on duplicate non-repeatable directives.
Field/argument directive wiring crates/wesley-core/src/adapters/apollo.rs	Threads repeatable_directives through field, input field, and field/operation argument extraction functions.
Schema operation directive wiring crates/wesley-core/src/adapters/apollo.rs	Threads repeatable_directives through schema operation collection and argument extraction.
Tests and directive docs crates/wesley-core/tests/lowering_validation.rs, docs/reference/directives.md	Updates error message assertions, adds duplicate/repeatable directive tests, and documents the IR encoding rule.

Documentation Onboarding and Vocabulary Governance

Layer / File(s)	Summary
Assurance Capability Matrix docs/reference/assurance-capability-matrix.md, README.md, docs/ARCHITECTURE.md, docs/END_TO_END.md, docs/GUIDE.md, docs/README.md, docs/topics/assurance-evidence.md	New matrix page defining shipped/transitional/internal/concept states, referenced across README and guide docs to scope assurance claims.
Plain Wesley onboarding docs/topics/plain-wesley.md, docs/GUIDE.md, docs/README.md, docs/topics/README.md, docs/topics/docs-orientation.md	New first-hour guide with a GraphQL-to-Wesley vocabulary table and beginner/contributor tutorials, linked from onboarding entry points.
External Target Protocol docs/reference/external-target-protocol.md, docs/guides/extending.md, docs/guides/module-authoring.md, docs/reference/project-manifest.md, docs/topics/extension-modules.md, docs/topics/README.md	New MVP spec for external-process target descriptors, request/response envelopes, and host enforcement, cross-referenced from module/extension docs.
Security tooling policy docs/topics/security-tooling.md, SECURITY.md, docs/topics/ci-workflows.md, docs/topics/validation.md, docs/topics/README.md	New page defining baseline gates and admission rules, referenced from SECURITY.md and CI/validation docs.
First-PR contributor path docs/topics/contributing/first-pr.md, CONTRIBUTING.md, docs/governance/DOCUMENTATION_STANDARD.md, docs/topics/docs-maintenance.md, docs/truth-manifest.json, CHANGELOG.md	New contributor onboarding page, updated starter-issue criteria, new vocabulary alias rule, and manifest/changelog registrations.

Rust-Native IR Benchmark Tooling

Layer / File(s)	Summary
bench-ir implementation xtask/src/main.rs	Adds cargo xtask bench-ir command with fixture generation, timed lowering, IR metrics, and JSON report output plus tests.
Design doc migration docs/design/0013-.../*, docs/design/0015-.../*, docs/design/0016-.../*, docs/design/0017-.../*	Updates evidence docs to reference cargo xtask bench-ir in place of retired pnpm perf:ir.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• Docs: add plain Wesley onboarding path #678: Directly requested the Plain Wesley onboarding docs track, vocabulary map, tutorials, and vocabulary alias rule implemented in this PR.
• Source: reject duplicate non-repeatable custom directives #683: Requests the same duplicate non-repeatable directive handling and repeatable-directive preservation implemented in apollo.rs and tested in lowering_validation.rs.
• Security: evaluate repo-specific advisory and static-analysis gates #684: Requests security tooling/scanner-fit posture documentation directly implemented via security-tooling.md and SECURITY.md updates.
• Evidence: restore Rust-native IR performance baseline #681: Requests restoring/adding a Rust-native performance benchmark, implemented via cargo xtask bench-ir and referencing design docs.
• Platform: specify external target protocol MVP #680: Requests an external target executable protocol spec, directly implemented via external-target-protocol.md.
• Docs: publish assurance capability matrix #679: Requests clarifying which assurance surfaces are shipped, directly implemented via the Assurance Capability Matrix.

Possibly related PRs

• flyingrobots/wesley#513: Both PRs modify apollo.rs and lowering_validation tests around directive alias canonicalization and duplicate-directive rejection semantics.

Suggested labels: Website

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The diff also adds unrelated assurance, security, benchmark, and IR-lowering changes that are not required by #678.	Split or remove the unrelated assurance, security, benchmark, and apollo/xtask changes so this PR stays scoped to the Plain Wesley docs work.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The Plain Wesley page, term map, tutorials, vocabulary rule, and routing updates align with #678's acceptance criteria.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main change: adding a Plain Wesley onboarding path.
Description check	✅ Passed	The description covers the required template sections with summary, rationale, changes, evidence, testing, risk, and backout details.

✨ 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 docs/plain-wesley-onboarding

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c576d292d0

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

[github-actions]

🔍 The Case of Pull Request #686

Schema Sets

• ecommerce
• reference

Schema Set ecommerce

Plain-English Readout

• Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
• Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
• Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.

🕵️ SHA-lock HOLMES full report for ecommerce (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for ecommerce (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for ecommerce (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.

---

Schema Set reference

Plain-English Readout

• Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
• Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
• Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.

🕵️ SHA-lock HOLMES full report for reference (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for reference (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for reference (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.

---

📚 Glossary (what the Holmes terms mean)

• HOLMES: Wesley’s main evidence investigation. It decides whether the cited proof is strong enough to justify shipping this commit.
• WATSON: An independent verification pass. It checks Holmes’s citations and score math instead of trusting them blindly.
• MORIARTY: A readiness forecast over time. It is advisory trend analysis, not the release gate itself.
• Schema coverage score (SCS): How much of the schema has direct supporting evidence across generated artifacts and cited proof.
• Test confidence index (TCI): How much test evidence exists for constraints, policies, relationships, and operations.
• Migration risk index (MRI): How risky the schema change is to roll out. Lower is better.
• Evidence trust: Whether the report is backed by exact citations, whole-file citations, or coarse references. Weak trust means the claim may be directionally right but not specific enough to trust blindly.
• Citation quality: A count of exact line-span citations versus whole-file or coarse references.
• ELEMENTARY: Ready to ship based on the current evidence.
• REQUIRES INVESTIGATION: More work or review is needed before shipping.
• YOU SHALL NOT PASS: Do not ship this change in its current state.

---

Machine-readable reports are grouped by schema set in workflow artifacts.

---

Filed at 221B Repository Street

[flyingrobots]

Activity Summary

Issue	Severity	Source	File	Commit / Action	Outcome
Remove unset metadata from expected IR keys	P2	Codex review	docs/topics/plain-wesley.md	cf0730e5	Tutorial now tells readers to expect version and types; resolved PRRT_kwDOPoavfs6OUWlP.
PR description missed standard sections	P4	Self / hygiene	PR metadata	PR body edit	Added Why, Changes, Method Evidence, Tracker Hygiene, Risk, Backout, Testing, and Checklist sections.

Validation:

• RED: docs assertion failed while docs/topics/plain-wesley.md still claimed metadata as an expected top-level key.
• GREEN: same assertion passes after the fix.
• Actual CLI check: wesley schema lower --json output includes version and types and omits metadata for the tutorial schema.
• pnpm exec prettier --check docs/topics/plain-wesley.md
• cargo xtask docs-check
• git diff --check origin/hardening/rust-validator-literals...HEAD
• pnpm run preflight
• pre-push Rust product preflight

Merge gate note: all GitHub Actions checks are passing; CodeRabbit is still queued at the time of this summary.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (3)

crates/wesley-core/src/adapters/apollo.rs (1)

908-960: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider consolidating the near-duplicate argument-extraction pipelines.

field_argument_from_input_value and operation_argument_from_input_value are structurally identical (name/type extraction, default value parsing, directive extraction), differing only in the returned struct type (FieldArgument vs OperationArgument). This PR had to apply the same repeatable_directives threading change to both independently — a sign that future directive/argument logic changes will need to be kept in sync manually across two call sites.

♻️ Possible consolidation approach

+struct ArgumentParts {
+    name: String,
+    description: Option<String>,
+    r#type: TypeReference,
+    default_value: Option<serde_json::Value>,
+    directives: IndexMap<String, serde_json::Value>,
+}
+
+fn argument_parts_from_input_value(
+    input_value: cst::InputValueDefinition,
+    area: &'static str,
+    repeatable_directives: &BTreeSet<String>,
+) -> Result<ArgumentParts, WesleyError> {
+    // shared name/type/default_value/directives extraction
+}

Then field_argument_from_input_value and operation_argument_from_input_value become thin wrappers mapping ArgumentParts into their respective structs.

Also applies to: 3547-3670

🤖 Prompt for 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.

In `@crates/wesley-core/src/adapters/apollo.rs` around lines 908 - 960, The
argument-extraction logic is duplicated between field and operation handling, so
future changes must be applied in two places. Factor the shared
name/type/default-value/directive parsing out of field_argument_from_input_value
and operation_argument_from_input_value into a common helper or ArgumentParts
builder, then keep each function as a thin wrapper that maps the shared result
into FieldArgument or OperationArgument. Preserve the repeatable_directives
threading through ApolloLoweringAdapter::extract_directives_with_repeatability
and the existing error handling.

xtask/src/main.rs (1)

3133-3155: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Minor: command_label computed twice.

run_command now computes command_label(program, args) only to discard it before delegating to run_command_no_label, which recomputes the same label. Passing the already-computed label through would avoid the redundant formatting, though the cost is negligible here.

🤖 Prompt for 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.

In `@xtask/src/main.rs` around lines 3133 - 3155, `run_command` and
`run_command_no_label` are computing the same `command_label(program, args)`
twice; avoid the redundant formatting by passing the already-computed label from
`run_command` into `run_command_no_label` (or otherwise reusing it) so the
shared command string is created once and used consistently in the spawn error
and `CommandFailed` path.

docs/topics/docs-maintenance.md (1)

20-21: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Keep this rule aligned with the canonical vocabulary policy.

This narrows the standard by dropping the “link to a definition page” option, which makes the maintenance guide drift from docs/governance/DOCUMENTATION_STANDARD.md.

♻️ Suggested tweak

-- Give every new public noun a plain-English alias, or mark it
--   internal/experimental near its first use.
+- Follow the vocabulary rule in `docs/governance/DOCUMENTATION_STANDARD.md`:
+  give new public nouns a plain-English alias, link to a definition page, or
+  mark them internal/experimental near first use.

🤖 Prompt for 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.

In `@docs/topics/docs-maintenance.md` around lines 20 - 21, The docs-maintenance
rule is out of sync with the canonical vocabulary policy because it removes the
“link to a definition page” option. Update the guidance in docs-maintenance to
match the policy in DOCUMENTATION_STANDARD by allowing the same supported
pattern for new public nouns, and keep the wording aligned with the existing
public noun/vocabulary rules rather than narrowing it.

🤖 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/reference/external-target-protocol.md`:
- Around line 89-91: Tighten the `command.program` guidance in the external
target protocol docs so “descriptor-relative” is not ambiguous about unsafe
paths. Update the wording around the relevant `command.program` rules to
explicitly reject `../` traversal, symlink escape, and other
canonicalization-based bypasses before launch, and keep the existing
deterministic-resolution constraint aligned with the `command.program` contract.

---

Nitpick comments:
In `@crates/wesley-core/src/adapters/apollo.rs`:
- Around line 908-960: The argument-extraction logic is duplicated between field
and operation handling, so future changes must be applied in two places. Factor
the shared name/type/default-value/directive parsing out of
field_argument_from_input_value and operation_argument_from_input_value into a
common helper or ArgumentParts builder, then keep each function as a thin
wrapper that maps the shared result into FieldArgument or OperationArgument.
Preserve the repeatable_directives threading through
ApolloLoweringAdapter::extract_directives_with_repeatability and the existing
error handling.

In `@docs/topics/docs-maintenance.md`:
- Around line 20-21: The docs-maintenance rule is out of sync with the canonical
vocabulary policy because it removes the “link to a definition page” option.
Update the guidance in docs-maintenance to match the policy in
DOCUMENTATION_STANDARD by allowing the same supported pattern for new public
nouns, and keep the wording aligned with the existing public noun/vocabulary
rules rather than narrowing it.

In `@xtask/src/main.rs`:
- Around line 3133-3155: `run_command` and `run_command_no_label` are computing
the same `command_label(program, args)` twice; avoid the redundant formatting by
passing the already-computed label from `run_command` into
`run_command_no_label` (or otherwise reusing it) so the shared command string is
created once and used consistently in the spawn error and `CommandFailed` path.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 13b61c8d-b827-400e-b01d-8495e4bfe944

📥 Commits

Reviewing files that changed from the base of the PR and between f52865a and b1ad1b3.

📒 Files selected for processing (36)

• CHANGELOG.md
• CONTRIBUTING.md
• README.md
• SECURITY.md
• crates/wesley-core/src/adapters/apollo.rs
• crates/wesley-core/tests/lowering_validation.rs
• docs/ARCHITECTURE.md
• docs/END_TO_END.md
• docs/GUIDE.md
• docs/README.md
• docs/design/0013-rust-ir-parity-sentinel/EVIDENCE_rust-core-performance-baseline.md
• docs/design/0013-rust-ir-parity-sentinel/SOURCE_wesley-core-rs-ir-contract-and-fixtures.md
• docs/design/0013-rust-ir-parity-sentinel/rust-ir-parity-sentinel.md
• docs/design/0015-resilience-policy-boundary/resilience-policy-boundary.md
• docs/design/0016-rust-core-binding-observatory/EVIDENCE_rust-core-binding-and-memory-baselines.md
• docs/design/0016-rust-core-binding-observatory/rust-core-binding-observatory.md
• docs/design/0017-rust-native-front-door-and-node-retirement/PARITY_SENTINEL_ARCHIVE.md
• docs/governance/DOCUMENTATION_STANDARD.md
• docs/guides/extending.md
• docs/guides/module-authoring.md
• docs/reference/assurance-capability-matrix.md
• docs/reference/directives.md
• docs/reference/external-target-protocol.md
• docs/reference/project-manifest.md
• docs/topics/README.md
• docs/topics/assurance-evidence.md
• docs/topics/ci-workflows.md
• docs/topics/contributing/first-pr.md
• docs/topics/docs-maintenance.md
• docs/topics/docs-orientation.md
• docs/topics/extension-modules.md
• docs/topics/plain-wesley.md
• docs/topics/security-tooling.md
• docs/topics/validation.md
• docs/truth-manifest.json
• xtask/src/main.rs

[flyingrobots]

Activity Summary

Item	Severity	Source	File	Fix commit	Outcome
Expected IR keys included skipped metadata	P2	Review thread PRRT_kwDOPoavfs6OUWlP	docs/topics/plain-wesley.md	cf0730e5	Tutorial now verifies version and types; thread resolved/outdated.
command.program path safety left traversal and symlink escapes ambiguous	P1	Review thread PRRT_kwDOPoavfs6OZSNY	docs/reference/external-target-protocol.md	55acf17b	Descriptor-relative executable rules now reject absolute paths, .., and symlink/canonicalization escapes before launch; thread resolved/outdated.
Vocabulary release-gate wording drifted from documentation standard	P3	Review nit	docs/topics/docs-maintenance.md	0856f2b7	Vocabulary rule now points to the governing docs standard and allows plain alias, definition link, or internal/experimental marker.
xtask command labels were computed through a redundant helper path	P3	Review nit	xtask/src/main.rs	70878ba9	run_command_with_label now reuses a single computed label path.
GraphQL field and operation argument extraction duplicated adapter logic	P3	Review nit	crates/wesley-core/src/adapters/apollo.rs	84134ff0	Shared ArgumentParts extraction helper preserves existing diagnostics while removing duplicate extraction code.

Validation:

• RED/GREEN checks were run for each item before the corresponding fix commit.
• cargo run --bin wesley -- schema lower --schema <tmp>/schema.graphql --json verified the onboarding IR keys.
• cargo xtask docs-check passed.
• cargo test -p xtask passed.
• cargo test -p wesley-core --test lowering_validation -- --nocapture passed.
• cargo test -p wesley-core --test operation_analysis -- --nocapture passed.
• cargo clippy -p wesley-core --all-targets -- -D warnings passed.
• git diff --check origin/hardening/rust-validator-literals...HEAD passed.
• pnpm run preflight passed locally.
• GitHub checks for docs: add plain Wesley onboarding path #686 are green, including CodeRabbit.