docs(agents): align AGENTS.md with docs/CONTRIBUTING conventions

AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md
+
+## Workflow
+- Before contributing, see `CODE_OF_CONDUCT.md`. For SEAL Certifications, also see `docs/pages/certs/contributions.mdx`. To take ownership of a framework, see `docs/pages/contribute/stewards`.
+- PRs target `develop` branch.
+- Setup: `pnpm install`
+- Dev server: `pnpm exec just serve` (generators + Vocs on :5173)
+- Build/verify: `pnpm run docs:build` then `pnpm run docs:preview` (preview available on :4173)
+- Lint: `just lint` (cspell + markdownlint on `docs/pages/**/*.mdx`)
+- Devcontainer: `.devcontainer/devcontainer.json` (pre-installs pnpm/Node/tools)
+
+## Content Structure
+- New/expanded pages: Copy `docs/pages/config/template.mdx`
+- Frontmatter required:
+  ```
+  title: "Page Title | Security Alliance"
+  description: "140-160 chars, keywords/action verbs"
+tags:
+  - Engineer/Developer
+  - Security Specialist
+  - Operations & Strategy
+contributors:
+  - role: wrote
+    users: [username]
+  - role: reviewed
+    users: []
+  - role: fact-checked
+    users: []
+  ```
+- Sidebar: Update `vocs.config.tsx` items; `dev: true` for WIP (hides on main site)
+- **Never edit**: `index.mdx` files are auto-generated by the build command (do not create or edit manually).
+- Images: do not commit images to the repo. In the PR description (or a PR comment), attach the images and flag that they need uploading. A maintainer or a steward will trigger the `/img-bot` workflow, which uploads to S3 and posts the resulting links back as a PR comment. Then, use those links in the PR content.
+- Generators run on build: tags, indexes, mermaid, printables, certs
+
+## Conventions Agents Miss
+- Explain: Non-technical first → technical depth
+- Language: Direct/technical, no 1st person ("implement X" not "I suggest")
+- Playbooks/templates: Top `> 🔑 **Key Takeaway**:` (<40 words summary)
+- Sections: Practical guidance (steps/checklist), Why important (incidents), Pitfalls/examples, Cheat sheet, Further reading
+- Tech details: Balanced (detailed for AWS/Cloudflare/etc., generic timeless principles)
+- Links: Descriptive; Resources section; relative internal paths
+- Frontmatter precision: title: "Page | Security Alliance" (&lt;60 chars or "| SEAL"), description: 140-160 chars (action verbs/keywords like tool names/attacks/standards), contributors: add github username under the appropriate role (wrote|reviewed|fact-checked). First-time contributors must also register a profile in `docs/pages/config/contributors.json` (see "Contributors database" below).
+- Contributors database: first-time contributors must register a profile in `docs/pages/config/contributors.json` keyed by GitHub username. Structure: 
+```
+"<github-username>": {
+  "slug": "<github-username>",
+  "name": "<Full Name>",
+  "avatar": "https://avatars.githubusercontent.com/<github-username>",
+  "github": "https://github.com/<github-username>",
+  "twitter": null,
+  "website": null,
+  "company": null,
+  "role": "contributor",
+  "job_title": null,
+  "description": null,
+  "badges": []
+}
+```
+Leave `badges: []` and `role: "contributor"` when self-registering as badges and specific roles are assigned by maintainers.
+- Style: American English; objective/explanatory tone (no simplifications); introduce acronyms; future-proof; no full-AI content (grammar ok); mermaid; images via PR comments → S3 (/img-bot)
+- New pages: MUST update vocs.config.tsx sidebar items (dev: true for WIP)
+- WIP pages: Add stub notice &gt; ⚠️ Stub/in progress, help contribute/expand
+
+## Commits/PRs
+- Sign: `git commit -S`; amend unsigned via rebase/edit/amend-S/continue; force-push
+- Pre-PR: Build + preview locally; update contributors.json if new
+- CI enforces: Spellcheck comments PRs, mdlint, preview deploys, vocs-config reminders
+- Unsigned commits fix: git rebase -i HEAD~N; pick→edit; git commit --amend -S --no-edit &amp;&amp; git rebase --continue (repeat); git push --force; verify git log --show-signature