docs(architecture): reset subsystem docs (#1184)

Author: drew

.agents/skills/build-from-issue/SKILL.md

@@ -185,7 +185,7 @@ gh issue comment <id> --body "$(cat <<'EOF'
 - <risk or unknown that may need human input>
 
 ### Documentation Impact
-- <which architecture/ docs will need updating, or "None expected">
+- <docs expected per AGENTS.md, or "None expected">
 
 ---
 *Revision 1 — initial plan*
@@ -431,18 +431,9 @@ Do not proceed to PR creation if E2E verification is not green.
 
 ### Step 11: Update Documentation
 
-Use the `arch-doc-writer` sub-agent to update architecture documentation. Use the Task tool:
-
-```
-Task tool with subagent_type="arch-doc-writer"
-```
-
-In the prompt, provide:
-- Which files were changed and why (from the plan + any deviations)
-- The issue context (what was built/fixed)
-- Which architecture docs in `architecture/` are likely affected
-
-Launch one `arch-doc-writer` instance per documentation file that needs updating. If no documentation changes are needed, the `arch-doc-writer` will make that determination.
+Review the documentation requirements in `AGENTS.md` and update any affected
+docs as part of the implementation. Keep documentation changes scoped to the
+behavior or subsystem that changed.
 
 ### Step 12: Commit and Push
 
@@ -502,10 +493,9 @@ Closes #<issue-id>
 ## Checklist
 - [x] Follows Conventional Commits
 - [x] Commits are signed off (DCO)
-- [x] Architecture docs updated (if applicable)
 
 **Documentation updated:**
-- `<architecture/doc.md>`: <what was updated>
+- `<doc path>`: <what was updated, or "None needed">
 EOF
 )"
 ```
@@ -537,7 +527,7 @@ PR: [#<pr-number>](https://github.com/OWNER/REPO/pull/<pr-number>)
 - E2E: <count or N/A>
 
 ### Docs updated
-- <list of updated architecture docs, or "None needed">
+- <list of updated docs, or "None needed">
 
 The issue will auto-close when the PR is merged.
 EOF
@@ -691,7 +681,6 @@ User says: "Build issue #42"
 7. Add unit tests for pagination logic, integration tests for both endpoints
 8. `mise run pre-commit` passes on first attempt
 9. E2E tests skipped (no changes under `e2e/`)
-10. `arch-doc-writer` updates `architecture/gateway.md` with pagination details
 10. Commit, push, create PR with `Closes #42`
 11. Post summary comment on issue with PR link
 12. Update labels: remove `state:in-progress` + `state:review-ready`, add `state:pr-opened`

.agents/skills/create-github-pr/SKILL.md

@@ -158,7 +158,6 @@ PR descriptions must follow the project's [PR template](.github/PULL_REQUEST_TEM
 ## Checklist
 - [ ] Follows Conventional Commits
 - [ ] Commits are signed off (DCO)
-- [ ] Architecture docs updated (if applicable)
 ```
 
 Populate the testing checklist based on what was actually run. Check boxes for steps that were completed.
@@ -193,7 +192,6 @@ Closes #456
 
 - [x] Follows Conventional Commits
 - [x] Commits are signed off (DCO)
-- [ ] Architecture docs updated (if applicable)
 EOF
 )"
 ```

.agents/skills/fix-security-issue/SKILL.md

@@ -157,24 +157,10 @@ If the review identified a specific exploit scenario, verify that it is no longe
 
 ## Step 7: Update Documentation
 
-Use the `arch-doc-writer` sub-agent to update any architecture documentation affected by the fix. Use the Task tool:
-
-```
-Task tool with subagent_type="arch-doc-writer"
-```
-
-In the prompt, provide:
-- Which files were changed and why
-- The security context (what vulnerability was fixed)
-- Which architecture docs in `architecture/` are likely affected
-
-The `arch-doc-writer` will determine which docs need updating and make the changes. Common cases include:
-- A new validation layer or middleware was added
-- An API contract changed (new required headers, changed error responses, etc.)
-- Access control or authentication flow was modified
-- Network or infrastructure security boundaries changed
-
-If the fix is purely internal (e.g., switching to parameterized queries with no external behavior change), documentation updates may not be needed -- let the `arch-doc-writer` make that determination.
+Review the documentation requirements in `AGENTS.md` and update any affected
+docs as part of the security fix. If the fix is purely internal, such as
+switching to parameterized queries with no external behavior change,
+documentation updates may not be needed.
 
 ## Step 8: Commit, Push, and Open PR
 
@@ -232,7 +218,7 @@ Closes #<issue-id>
 - **Integration/E2E:** <test file and what it covers, or "N/A" if not applicable>
 
 ### Documentation Updated
-- `<architecture/doc.md>`: <what was updated>
+- `<doc path>`: <what was updated, or "None needed">
 
 ### Verification
 <how the fix was verified -- tests passed, exploit scenario tested, etc.>
@@ -281,7 +267,7 @@ User says: "Fix security issue #42"
 4. Create branch `fix/security-42-input-sanitization`
 5. Implement the fix
 6. Add unit tests for the sanitization function and an integration test for the endpoint
-7. Run `arch-doc-writer` to update `architecture/sandbox.md` with the new input validation layer
+7. Update affected documentation per `AGENTS.md`, if needed
 8. Commit, push, and open PR with `Closes #42`
 9. Report the PR link and changes to the user
 
@@ -294,7 +280,7 @@ User says: "Fix any ready security issues"
 3. Fetch the review comment -- determination is "Legitimate concern"
 4. Implement parameterized queries
 5. Add `test_rejects_sql_injection_in_search_query` unit test and e2e test for the search endpoint
-6. `arch-doc-writer` updates API docs to note the query parameter validation
+6. Update affected documentation per `AGENTS.md`, if needed
 7. Commit, push, open PR with `Closes #78`, report to user
 
 ### Issue with non-actionable review

.agents/skills/generate-sandbox-policy/SKILL.md

@@ -155,19 +155,19 @@ You may need to go back and forth a few times. Keep the loop tight:
 Read the full policy schema reference:
 
 ```
-Read architecture/security-policy.md
+Read docs/reference/policy-schema.mdx
 ```
 
 Key sections to reference:
-- **Full YAML Policy Schema** — top-level structure
+- **Policy Schema Reference** — top-level structure
 - **`network_policies`** — rule structure
 - **`NetworkEndpoint`** fields — host, port, protocol, tls, enforcement, access, rules, allowed_ips
 - **`L7Rule` / `L7Allow`** — method + path matching
 - **Access Presets** — `read-only`, `read-write`, `full`
 - **Private IP Access via `allowed_ips`** — CIDR allowlist for private IP space
 - **Validation Rules** — what combinations are valid/invalid
 
-Also read the example policy for real-world patterns. The default policy is baked into the community base image (`ghcr.io/nvidia/openshell-community/sandboxes/base:latest`). For reference, consult the policy schema documentation:
+Also read the architecture overview for enforcement context. The default policy is baked into the community base image (`ghcr.io/nvidia/openshell-community/sandboxes/base:latest`). For reference, consult:
 
 ```
 Read architecture/security-policy.md
@@ -567,7 +567,8 @@ private_services:
 
 ## Additional Resources
 
-- Full policy schema: [architecture/security-policy.md](../../../architecture/security-policy.md)
+- Full policy schema: [docs/reference/policy-schema.mdx](../../../docs/reference/policy-schema.mdx)
+- Enforcement overview: [architecture/security-policy.md](../../../architecture/security-policy.md)
 - Default policy: baked into the community base image (`ghcr.io/nvidia/openshell-community/sandboxes/base:latest`)
 - Rego evaluation rules: [sandbox-policy.rego](../../../crates/openshell-sandbox/data/sandbox-policy.rego)
 - For translation examples from real API docs, see [examples.md](examples.md)

AGENTS.md

@@ -196,6 +196,17 @@ ocsf_emit!(event);
 - Fern PR previews run through `.github/workflows/branch-docs.yml`, and production publish runs through the `publish-fern-docs` job in `.github/workflows/release-tag.yml`.
 - Use the `update-docs` skill to scan recent commits and draft doc updates.
 
+### Architecture Docs
+
+- Architecture docs are short canonical subsystem overviews, not exhaustive implementation notes.
+- Update one of the existing top-level architecture docs before adding a new file.
+- Put useful crate-specific details in the relevant crate `README.md`.
+- Add a new top-level architecture doc only when explicitly requested or when an RFC-level design needs a stable home.
+- Keep architecture docs focused on stable boundaries, data/control flow, invariants, and operational constraints.
+- Remove stale detail instead of preserving it by default.
+- Do not include testing transcripts, historical debugging notes, long source-file inventories, or field-by-field schema references.
+- Put user-facing instructions in `docs/`, broad design proposals in `rfc/`, and temporary plans in ignored `architecture/plans/`.
+
 ## Security
 
 - Never commit secrets, API keys, or credentials. If a file looks like it contains secrets (`.env`, `credentials.json`, etc.), do not stage it.