docs: audit cleanup (dedup rules, add SECURITY/DECISIONS/PR template)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## What
+
+<!-- One purpose. Link the issue: Fixes #… -->
+
+## Why
+
+<!-- Problem / issue context. -->
+
+## How to verify
+
+<!-- Commands, test names, manual steps. -->
+
+## Risk / blast radius
+
+- Shared files/symbols touched:
+- Do-not-touch list:
+
+## Checklist
+
+- [ ] One purpose; fix ≠ feature; refactor separate ([core/git.md](../core/git.md)).
+- [ ] Local gates run: lint, types, tests, build ([core/workflow.md](../core/workflow.md)).
+- [ ] No secrets, no debug code, no unrelated files.
+- [ ] Tests added/updated; deny tests for new guarded surfaces (401/403).
+- [ ] Docs updated (list paths) **or** explicit "unchanged because …".
+- [ ] `CHANGELOG` entry under `[Unreleased]` if user-visible/API/security.
+- [ ] Legal trigger table walked if processing/PII/tools changed.
+- [ ] Regression matrix walked for risky changes ([core/regression.md](../core/regression.md)).

AGENTS.md

@@ -28,6 +28,7 @@ This file is a **router**, not an encyclopedia. Read only the files the current
 | --- | --- |
 | Any session | [core/workflow.md](core/workflow.md), [core/context-budget.md](core/context-budget.md) |
 | New feature / route | [core/architecture.md](core/architecture.md), [templates/feature-spec.md](templates/feature-spec.md), [testing/strategy.md](testing/strategy.md) |
+| Product definition / PRD | [templates/PRD.md](templates/PRD.md) |
 | Refactor / bugfix | [core/regression.md](core/regression.md), [core/clean-code.md](core/clean-code.md) |
 | UI implementation | [skills/frontend-ui/SKILL.md](skills/frontend-ui/SKILL.md), [frontend/ui.md](frontend/ui.md), [frontend/ux.md](frontend/ux.md), [frontend/components.md](frontend/components.md) |
 | Design tokens / themes | [frontend/design.md](frontend/design.md) |

CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this collection are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+
+- `SECURITY.md` (root) — vulnerability reporting + pointer to `security/`.
+- `DECISIONS.md` (root) — canonical decision log (referenced by `core/docs-system.md`, `legal/legal-maintenance.md`).
+- `.github/PULL_REQUEST_TEMPLATE.md` — mirrors `checklists/pr.md`.
+- `skills/README.md` — skill index.
+- Subfolder-README rule in `core/context-budget.md`.
+
+### Changed
+
+- REST ownership resolved: `skills/rest-guidelines/SKILL.md` owns the wire format; `backend/api.md` owns the API topic. Duplicated tables removed from `backend/api.md`.
+- Deduplicated rule copies: security review checklist (`security/web-api.md` → skill), video scrubbing (`frontend/scroll-motion.md` → skill), session docs (`checklists/session.md` → `core/docs-system.md`), escalation gates (`core/workflow.md` → AGENTS/security).
+- Lessons date format documented as `YYYY-MM` (matches existing rows).
+- `README.md`: reuse/license note added; copy/submodule guidance softened; budget wording clarified.
+- `AGENTS.md` routing now reaches `templates/PRD.md`.
+- `MANIFEST.md` heading `tooling` → `Tooling`; ownership map split for API topic vs REST wire format.
+
 ## [1.0.0] - 2026-09-17
 
 ### Added

DECISIONS.md

@@ -0,0 +1,14 @@
+# Decision Log
+
+Dated one-liners for rule and structure decisions of this collection, including
+"checked, unchanged" outcomes. Append-only; supersede, never rewrite.
+
+Format: `YYYY-MM-DD: <decision or check> — <reason>`.
+
+## 2026-09-18
+
+- REST wire format is canonical in `skills/rest-guidelines/SKILL.md`; `backend/api.md` owns the API topic (auth, validation, endpoint DoD). Reason: remove dual ownership flagged in the audit.
+- No license granted for this collection; `README.md` states that reuse requires permission. Reason: proprietary decision by the maintainer.
+- Added root `SECURITY.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `DECISIONS.md`, `skills/README.md`. Reason: close hygiene gaps (no reporting path, no PR template, no decision-log home, no skill index).
+- Lessons keep `YYYY-MM` date granularity; `lessons/README.md` format was corrected to match the rows. Reason: docs must match the data.
+- `lessons/*` rows stay even when the rule is promoted into a topic file. Reason: lessons are the append-only origin; topic files are canonical ([lessons/README.md](lessons/README.md)).

MANIFEST.md

@@ -11,19 +11,22 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s
 | [README.md](README.md) | Human onboarding, adoption, customization, limits | Adopting the collection |
 | [MANIFEST.md](MANIFEST.md) | This index | Adding, renaming, auditing files |
 | [CHANGELOG.md](CHANGELOG.md) | Release history of the collection | Updating the collection |
+| [DECISIONS.md](DECISIONS.md) | Decision log (rule/structure decisions, "unchanged" checks) | Rule lifecycle, audits |
+| [SECURITY.md](SECURITY.md) | Vulnerability reporting + scope for this collection | Reporting a security issue |
 | [CLAUDE.md](CLAUDE.md) | Pointer `@AGENTS.md` for Claude Code | Tool reads it automatically |
 | [GEMINI.md](GEMINI.md) | Pointer `@AGENTS.md` for Gemini CLI | Tool reads it automatically |
 | [.github/copilot-instructions.md](.github/copilot-instructions.md) | Pointer for GitHub Copilot | Tool reads it automatically |
 | [opencode.json](opencode.json) | Tool permissions (allow/deny/ask), subagent roles | OpenCode setup |
 
-## tooling
+## Tooling
 
 | Path | Purpose | Read when |
 | --- | --- | --- |
 | [scripts/check-docs.mjs](scripts/check-docs.mjs) | Validates budgets, skill frontmatter, links, MANIFEST coverage | Docs/CI changes |
 | [scripts/install-skills.mjs](scripts/install-skills.mjs) | Copies `skills/` into `.agents/skills/` and `.claude/skills/` | Adopting skills into a project |
 | [examples/hooks/README.md](examples/hooks/README.md) | Deterministic gate hook examples (Claude Code) | Setting up enforcement |
 | [.github/workflows/docs-check.yml](.github/workflows/docs-check.yml) | CI job running the docs check on push/PR | CI changes |
+| [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md) | PR description + checklist | Opening a PR |
 
 ## Rule ownership — canonical file per topic
 
@@ -39,9 +42,11 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s
 | Consent, Impressum, BFSG | `legal/compliance-de.md` |
 | Overlays, scroll ownership | `frontend/scroll-motion.md` |
 | Accessibility baseline | `frontend/accessibility.md` |
-| API contracts | `backend/api.md` (+ `skills/rest-guidelines/`) |
+| API topic (auth, validation, endpoint DoD) | `backend/api.md` |
+| REST wire format (paths, JSON, methods, status, errors, pagination) | `skills/rest-guidelines/SKILL.md` |
 | Release ritual | `checklists/release.md` |
 | Rule lifecycle (add/delete) | `core/context-budget.md` |
+| Decision log | `DECISIONS.md` |
 
 ## core/ — process & engineering
 
@@ -138,6 +143,7 @@ Maintainer index — read when adding, renaming, or auditing files, **not** at s
 
 | Path | Purpose | Read when |
 | --- | --- | --- |
+| [skills/README.md](skills/README.md) | Skill index | Choosing a skill |
 | [skills/plan-first/SKILL.md](skills/plan-first/SKILL.md) | Plan before code | Any non-trivial task |
 | [skills/tdd-extraction/SKILL.md](skills/tdd-extraction/SKILL.md) | Derive failing test first | Bugs, features |
 | [skills/rest-guidelines/SKILL.md](skills/rest-guidelines/SKILL.md) | REST subset, OpenAPI duty | API design |

README.md

@@ -11,6 +11,8 @@ Canonical repository: https://github.com/Neuroklast/agent-documents
 git clone https://github.com/Neuroklast/agent-documents.git
 ```
 
+Reading/evaluating is unrestricted; copying or submoduling into another project requires permission — see [License / reuse](#license--reuse). Once permitted:
+
 Use in a target project (copy):
 
 ```powershell
@@ -40,7 +42,7 @@ Then point the target repo's root `AGENTS.md` at `docs/agent-docs/AGENTS.md` and
 4. Delete unused stack adapters and skills — the router must only point at files that exist.
 5. Optionally copy `opencode.json` and adjust permissions; copy `CLAUDE.md` / `GEMINI.md` / `.github/copilot-instructions.md` for tool compatibility.
 6. Add a short **Project facts** block to `AGENTS.md`: stack, package manager, check commands, deploy target. Never invent these — read the manifests.
-7. Install skills where your tools discover them: `node scripts/install-skills.mjs <target-repo>` (copies into `.agents/skills/` and `.claude/skills/`). opencode and Codex read `.agents/skills/`; Claude Code reads `.claude/skills/`.
+7. Install skills where your tools discover them: `node scripts/install-skills.mjs <target-repo>` (copies into `.agents/skills/` and `.claude/skills/`). opencode reads `.agents/skills/`; Claude Code reads `.claude/skills/` — verify the path for other tools.
 8. Optional: copy `examples/hooks/` and wire them into `.claude/settings.json` for deterministic gates.
 
 ## Monorepos
@@ -56,8 +58,8 @@ commands, package layout, and what differs from the root.
 AGENTS.md            Router: hard rules, routing table
 README.md            This file
 MANIFEST.md          Maintainer index (not read at session start)
-CHANGELOG.md         Release history of the collection
-CLAUDE.md / GEMINI.md / .github/copilot-instructions.md   Pointers
+CHANGELOG.md / DECISIONS.md / SECURITY.md   History, decision log, security policy
+CLAUDE.md / GEMINI.md / .github/*   Tool pointers + PR template
 opencode.json        Tool permissions (OpenCode)
 core/                Workflow, context budget, git, clean code, quality, architecture, regression, docs
 frontend/            UI, UX, design, components, accessibility, scroll/motion, performance
@@ -68,7 +70,7 @@ testing/             Strategy, unit, e2e, contracts/CI
 checklists/          Session, PR, release, launch
 lessons/             Distilled hard-won lessons by area
 roles/               Subagent role contracts (architect, reviewer, tester, …)
-skills/              Task-specific skills (SKILL.md per folder, Agent Skills spec)
+skills/              Task-specific skills (SKILL.md per folder; index in skills/README.md)
 templates/           PRD, ADR, feature spec, deviation record
 stack/               Next.js, Supabase, R2, TypeScript, C++/JUCE
 scripts/             check-docs.mjs, install-skills.mjs
@@ -78,7 +80,7 @@ examples/hooks/      Deterministic gate hook examples
 ## Principles
 
 - **MUST / NEVER / ALWAYS** phrasing. Bullets, not prose.
-- Every topic file ≤ 150 lines, every skill ≤ 100 lines. If a topic grows, split by concern and register it in `MANIFEST.md`.
+- Every markdown file except `AGENTS.md`/`MANIFEST.md` ≤ 150 lines; every skill ≤ 100 lines. If a topic grows, split by concern and register it in `MANIFEST.md`.
 - `MANIFEST.md` is a maintainer index; sessions read the `AGENTS.md` routing table only.
 - Facts over templates: no invented operator data, no invented APIs, no invented version numbers.
 - Structural gates (CI scripts, contract tests, hooks) beat prose bans. Markdown is the contract; enforcement lives in tooling.
@@ -89,7 +91,7 @@ examples/hooks/      Deterministic gate hook examples
 node scripts/check-docs.mjs
 ```
 
-Checks line budgets (AGENTS.md ≤ 120, MANIFEST ≤ 200, topic ≤ 150, skill ≤ 100), skill frontmatter
+Checks line budgets (AGENTS.md ≤ 120, MANIFEST ≤ 200, every other markdown file ≤ 150, skill ≤ 100), skill frontmatter
 (name/description per the Agent Skills spec), relative links, MANIFEST coverage,
 and prints a token estimate per file. CI runs it on every push and PR
 ([.github/workflows/docs-check.yml](.github/workflows/docs-check.yml)).
@@ -141,3 +143,7 @@ Git             protected main, required checks, no force-push
 - Update the matching topic file whenever a convention changes; new topic → new file + `MANIFEST.md` entry.
 - Keep `AGENTS.md` ≤ 120 lines. It is a router, not documentation.
 - Archive superseded docs with a banner instead of deleting history ([core/docs-system.md](core/docs-system.md)).
+
+## License / reuse
+
+No license is granted — all rights reserved. Copying, submoduling, or redistributing into another project requires permission from the maintainer; open an issue to ask.

SECURITY.md

@@ -0,0 +1,25 @@
+# Security Policy
+
+This repository is a portable governance collection (markdown). It ships no
+runtime code and no deployed service. The agent-facing security contracts live
+in [`security/`](security/security.md).
+
+## Reporting a vulnerability
+
+- Report privately via GitHub Security Advisories ("Report a vulnerability" on
+  the repository). Do not open a public issue.
+- Include: affected file/path, impact, reproduction, suggested fix.
+- We acknowledge within ~72 h and do not disclose details before a fix ships.
+
+## Scope
+
+- A wrong or unsafe rule is treated like a bug: open an issue with the affected
+  file and a concrete correction.
+- If a secret was committed: report privately; rotation happens before any
+  history cleanup (human approval required).
+
+## Baseline
+
+- [security/security.md](security/security.md) — secrets, least privilege, hardening, residual risk.
+- [security/web-api.md](security/web-api.md) — XSS, CSRF, SSRF, headers, uploads, rate limits.
+- [security/owasp-llm.md](security/owasp-llm.md) — OWASP LLM Top 10 agent rules.

backend/api.md

@@ -2,39 +2,9 @@
 
 Load for: any API endpoint or spec. Mandatory skill: [../skills/rest-guidelines/SKILL.md](../skills/rest-guidelines/SKILL.md).
 
-## Resource design
+## REST wire format
 
-- Paths: kebab-case, plural nouns, no verbs: `/api/v1/invoice-line-items`.
-- IDs are opaque strings (UUIDs), never sequential integers in public APIs.
-- snake_case JSON properties; plural names for arrays; `_at` for timestamps, `_date` for dates.
-- NEVER trailing slashes. NEVER RPC-style verbs (`/getUser`) unless the action is genuinely a process (`/imports`).
-- Additive-only changes within a version; breaking changes → new version.
-
-## Methods & status codes
-
-| Method | Semantics |
-| --- | --- |
-| GET | Safe, idempotent, cacheable where appropriate |
-| POST | Create; idempotency key for retryable creates |
-| PUT | Full replace |
-| PATCH | Partial merge |
-| DELETE | Idempotent removal |
-
-- 200 OK, 201 Created + `Location`, 202 Accepted (async), 204 No Content.
-- 400 validation, 401 unauthenticated, 403 unauthorized, 404 missing, 409 conflict, 422 semantic rejection, 429 rate limited (with retry info), 500 server error.
-- NEVER 200 with an error body.
-
-## Errors
-
-- `application/problem+json`: `type`, `title`, `status`, `detail`, `instance`.
-- NEVER stack traces, SQL, or internal identifiers in responses.
-- Validation errors: field-level detail, stable machine-readable codes.
-
-## Pagination & filtering
-
-- Cursor pagination default; opaque `next_cursor`; default page size ~50, max ~200.
-- Offset pagination only where the repo already does it.
-- Filters as query params (snake_case); never unbounded result sets.
+Paths, JSON shape, methods, status codes, problem+json errors, pagination, and versioning are canonical in [../skills/rest-guidelines/SKILL.md](../skills/rest-guidelines/SKILL.md). Do not restate or fork them here.
 
 ## Auth & limits
 

checklists/session.md

@@ -20,12 +20,7 @@ Definition of Done: [../core/quality.md](../core/quality.md).
 
 ## 3. Docs
 
-- [ ] Matching topic/feature docs updated.
-- [ ] `CHANGELOG` entry under `[Unreleased]` (behavior/API/security changes).
-- [ ] QA checklist updated for new/changed testable flows.
-- [ ] Lessons appended if an incident/pitfall occurred.
-- [ ] Legal trigger table walked (if processing/PII/tools changed) ([../legal/legal-maintenance.md](../legal/legal-maintenance.md)).
-- [ ] Or explicit: `Docs: unchanged because <reason>`.
+Walk the maintenance matrix in [../core/docs-system.md](../core/docs-system.md) and the legal trigger table ([../legal/legal-maintenance.md](../legal/legal-maintenance.md)); update each affected doc or record `Docs: unchanged because <reason>`.
 
 ## 4. Git
 

core/context-budget.md

@@ -16,6 +16,7 @@ MANIFEST.md is a maintainer index and is not part of the session read chain.
 - NEVER read whole docs trees "to be safe". That burns context and hides the relevant rule.
 - When a task spans areas, read at most 2–3 topic files plus the files those topics or the invoked skill name directly.
 - Load skills only when their description matches the task.
+- Subfolders get a `README.md` only when they hold a non-rule index (e.g. `lessons/`, `roles/`, `skills/`). Pure topic folders rely on `AGENTS.md` routing + `MANIFEST.md`.
 
 ## File size budgets
 

core/docs-system.md

@@ -37,7 +37,7 @@ Load for: every session end, when behavior or conventions change.
 ## Decision log
 
 - When a legal/compliance/architecture check happened but nothing changed, record a dated one-liner: `YYYY-MM-DD: checked <trigger>, unchanged because <reason>`.
-- The log lives next to the affected docs (e.g. in the legal maintenance file or the ADR list).
+- For this collection the log is [../DECISIONS.md](../DECISIONS.md); in a target project keep it next to the affected docs (e.g. legal maintenance file or the ADR list).
 
 ## Archive policy
 

core/workflow.md

@@ -45,8 +45,8 @@ Load for: every session.
 
 ## Escalation — stop and ask the human
 
-- Production deploy, destructive DB migration, data backfill.
-- `rm -rf`, force-push, history rewrite, secret rotation.
+Approval gates for deploys, destructive migrations, data backfills, `rm -rf`, history rewrite, force-push, and secret rotation are canonical in [AGENTS.md](../AGENTS.md) §Hard rules and [../security/security.md](../security/security.md) §Least privilege. Additionally stop and ask for:
+
 - Deviation from a safety rule (e.g. realtime/MISRA, see [../skills/c-realtime/SKILL.md](../skills/c-realtime/SKILL.md)).
 - Legal text wording, operator data, pricing/contract terms.
 

frontend/scroll-motion.md

@@ -46,10 +46,7 @@ Load for: scroll behavior, overlays, carousels, video scrubbing, z-index.
 
 ## Video scrubbing
 
-- NEVER drive `HTMLVideoElement.currentTime` in a scroll handler on the main thread as the default — it stalls mobile.
-- Preferred: pre-rendered frame sequence on canvas, or WebCodecs + canvas with a scroll timeline.
-- ALWAYS reduced-motion fallback: static poster/first frame.
-- See [../skills/video-scrubbing/SKILL.md](../skills/video-scrubbing/SKILL.md) before implementing.
+Scroll-bound video is implemented per [../skills/video-scrubbing/SKILL.md](../skills/video-scrubbing/SKILL.md) (frame-sequence/WebCodecs canvas, reduced-motion poster, mobile memory budget). Do not drive `HTMLVideoElement.currentTime` from a scroll handler by default.
 
 ## Multi-column builders
 

legal/legal-maintenance.md

@@ -43,7 +43,7 @@ If a change triggers nothing: record it explicitly — `YYYY-MM-DD: checked <tri
 ## Decision log
 
 - Append dated one-liners for every legal check, including "unchanged" decisions.
-- Keep the log next to the legal sources or in the project's docs.
+- In this collection the log is [../DECISIONS.md](../DECISIONS.md); in a target project keep it next to the legal sources.
 
 ## NEVER
 

lessons/README.md

@@ -18,7 +18,7 @@ Append-only table rows:
 
 | Date | Area | Lesson | Severity |
 | --- | --- | --- | --- |
-| YYYY-MM-DD | short area | one actionable sentence (what to do, not what happened) | low/med/high |
+| YYYY-MM | short area | one actionable sentence (what to do, not what happened) | low/med/high |
 
 Rules:
 

security/web-api.md

@@ -62,11 +62,4 @@ Load for: web/API security work, reviews, new endpoints, uploads.
 
 ## Review checklist
 
-- [ ] Inputs validated at the boundary.
-- [ ] AuthZ server-side on every mutation/foreign-ID read.
-- [ ] Outputs escaped/sanitized.
-- [ ] URLs/redirects validated by parsing.
-- [ ] Uploads authenticated + magic-byte checked.
-- [ ] Rate limits on abuse-prone endpoints.
-- [ ] No secrets/PII in logs or responses.
-- [ ] New origins in CSP.
+The security review checklist is canonical in [../skills/security-owasp/SKILL.md](../skills/security-owasp/SKILL.md). This file remains the reference for the web/API specifics above (injection, CSRF, SSRF, CORS, CSP, uploads, rate limiting, logging, embeds).