@jaimevalasek/aioson 1.6.0 → 1.7.2

package/template/.aioson/brains/site-forge/visual-patterns.brain.json

@@ -0,0 +1,205 @@
+{
+  "v": 1,
+  "agent": "site-forge",
+  "domain": "visual-patterns",
+  "desc": "CSS/animation/interaction patterns discovered while cloning real sites. Each node is a reusable lesson — quality-scored and anti-pattern aware. Use see[] to traverse related nodes.",
+  "updated": "2026-04-01",
+  "nodes": [
+    {
+      "id": "css-001",
+      "title": "CTA hover: mix-blend-mode:difference",
+      "tags": ["css", "hover", "cta", "button", "animation", "no-js", "blend-mode"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "White ::after pseudo-element with mix-blend-mode:difference creates color inversion on hover. Zero JS. Works on any background color automatically.",
+      "p": ".btn{position:relative;overflow:hidden} .btn::after{content:'';position:absolute;inset:0;background:white;mix-blend-mode:difference;transform:scaleX(0);transform-origin:0;transition:transform .3s cubic-bezier(.645,.045,.355,1)} .btn:hover::after{transform:scaleX(1)}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "background-color color transition on hover — color swap is weak compared to inversion effect",
+      "warn": "parent needs overflow:hidden; does not work if parent has background:transparent",
+      "see": ["css-002", "css-008"]
+    },
+    {
+      "id": "css-002",
+      "title": "Mobile menu: clip-path polygon() swipe",
+      "tags": ["css", "animation", "mobile", "menu", "drawer", "keyframes", "clip-path"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Mobile drawer wipes in from right using clip-path polygon animation — more cinematic than translateX slide. Requires @keyframes swipeIn/swipeOut.",
+      "p": "@keyframes swipeIn{0%{clip-path:polygon(101% 0%,100% 0%,101% 100%,116% 100%)}to{clip-path:polygon(0% 0%,101% 0%,101% 101%,0% 101%)}} .menu--open{animation:.6s cubic-bezier(.165,.84,.44,1) forwards swipeIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "transform:translateX(-100%) — generic slide, no visual drama",
+      "warn": "Menu must be position:fixed with full viewport size for clip-path to work correctly",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-003",
+      "title": "Accordion: grid-template-rows 0fr→1fr",
+      "tags": ["css", "accordion", "animation", "no-js", "grid", "mobile"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "CSS grid transition on grid-template-rows animates height without any JS height calculation. Modern and smooth.",
+      "p": ".accordion-content{display:grid;grid-template-rows:0fr;transition:grid-template-rows .7s cubic-bezier(.165,.84,.44,1)} .accordion-content--open{grid-template-rows:1fr} .accordion-inner{overflow:hidden}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "max-height hack or JS getBoundingClientRect height calculation",
+      "warn": "Inner child needs overflow:hidden for the 0fr collapse to work",
+      "see": ["css-007"]
+    },
+    {
+      "id": "css-004",
+      "title": "Link underline: dual linear-gradient background-position",
+      "tags": ["css", "hover", "link", "underline", "animation", "keyframes"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Two linear-gradients animated via background-position create a sliding underline that enters from left on hover and exits to right on mouse-leave. Pure CSS.",
+      "p": ".link{background-image:linear-gradient(currentColor,currentColor),linear-gradient(currentColor,currentColor);background-size:100% 1px,0% 1px;background-repeat:no-repeat;background-position:-200% 100%,-100% 100%;animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideOut} .link:hover{animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "text-decoration or border-bottom — no directional animation possible",
+      "warn": "Requires @keyframes ctaUnderlineSlideIn/Out; currentColor inherits from text color automatically",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-005",
+      "title": "Scroll reveal: IntersectionObserver + CSS class toggle",
+      "tags": ["css", "scroll", "reveal", "animation", "no-js-lib", "intersection-observer"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "IntersectionObserver adds .in-view class at 15% threshold; CSS transition handles opacity+translateY. Zero third-party libraries needed.",
+      "p": "// JS: const obs=new IntersectionObserver(entries=>entries.forEach(e=>e.isIntersecting&&e.target.classList.add('in-view')),{threshold:.15}); document.querySelectorAll('.reveal').forEach(el=>obs.observe(el)); // CSS: .reveal{opacity:0;transform:translateY(16px);transition:opacity .8s cubic-bezier(.23,1,.32,1),transform .8s cubic-bezier(.23,1,.32,1)} .reveal.in-view{opacity:1;transform:none}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "AOS library, ScrollReveal, GSAP ScrollTrigger for basic fade-up reveals — overkill",
+      "warn": "threshold:0.15 is the sweet spot; too low fires too early, too high never fires on short sections",
+      "see": ["css-007", "css-008"]
+    },
+    {
+      "id": "css-006",
+      "title": "Staggered card reveals with nth-child delay",
+      "tags": ["css", "animation", "stagger", "cards", "scroll", "reveal"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Add transition-delay via nth-child selectors on .reveal-stagger children. 0.1s increments per card.",
+      "p": ".reveal-stagger>*:nth-child(1){transition-delay:0s} .reveal-stagger>*:nth-child(2){transition-delay:.1s} .reveal-stagger>*:nth-child(3){transition-delay:.2s} .reveal-stagger>*:nth-child(4){transition-delay:.3s} .reveal-stagger>*:nth-child(5){transition-delay:.4s}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Keep delays short (0.1s increments); longer delays feel sluggish",
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-007",
+      "title": "Squarespace signature easing curves",
+      "tags": ["css", "easing", "animation", "cubic-bezier", "tokens"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Three distinct easing curves used consistently: reveal=smooth deceleration, cta=power ease, menu=fast-in/slow-out. Gives a unified, professional motion feel.",
+      "p": "--ease-sqsp-reveal:cubic-bezier(.23,1,.32,1); --ease-sqsp-cta:cubic-bezier(.645,.045,.355,1); --ease-sqsp-menu:cubic-bezier(.165,.84,.44,1)",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "ease, ease-in-out, linear — generic curves flatten the personality of the site",
+      "warn": null,
+      "see": ["css-001", "css-002", "css-003", "css-004", "css-005"]
+    },
+    {
+      "id": "css-008",
+      "title": "prefers-reduced-motion global override",
+      "tags": ["css", "accessibility", "animation", "best-practice"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Global @media prefers-reduced-motion override that collapses all durations to 0.01ms. Always include in globals.css — never skip.",
+      "p": "@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": null,
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-009",
+      "title": "Video background: autoPlay muted loop playsInline",
+      "tags": ["css", "video", "background", "hero", "mobile"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Hero video must have all 4 attributes to autoplay cross-browser. WebM first, MP4 fallback. Dark rgba overlay on top. Mobile swap via useEffect.",
+      "p": "<video autoplay muted loop playsinline preload=auto><source src=desktop.webm type=video/webm><source src=desktop.mp4 type=video/mp4></video><div style=position:absolute;inset:0;background:rgba(0,0,0,.52)></div>",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Using background-image: url() for video — use the real <video> element",
+      "warn": "Card carousel videos use preload=none; only hero is preload=auto",
+      "see": ["css-005"]
+    },
+    {
+      "id": "js-001",
+      "title": "Extract @keyframes via document.styleSheets iteration",
+      "tags": ["js", "extraction", "keyframes", "css", "cloning", "analysis"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Iterate document.styleSheets and cssRules to extract @keyframes verbatim. This is the ONLY way to get actual @keyframes — getComputedStyle never exposes them.",
+      "p": "const kf=[]; for(const s of document.styleSheets){try{for(const r of s.cssRules){if(r instanceof CSSKeyframesRule){kf.push({name:r.name,css:r.cssText})}}}catch(e){}} console.log(JSON.stringify(kf))",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "getComputedStyle(el).animation — returns resolved shorthand, never exposes @keyframes definitions",
+      "warn": "CORS will throw on cross-origin stylesheets — wrap in try/catch per sheet",
+      "see": ["js-002", "js-003"]
+    },
+    {
+      "id": "js-002",
+      "title": "MutationObserver scroll recording for DOM class changes",
+      "tags": ["js", "extraction", "cloning", "scroll", "animation", "mutationobserver"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Attach MutationObserver BEFORE starting scroll; record mutations at 8 checkpoints (0%, 12%, 25%, 37%, 50%, 62%, 75%, 87%, 100%). Each record: scrollY + changed elements + class diffs.",
+      "p": "const mutations=[]; const obs=new MutationObserver(ms=>ms.forEach(m=>{mutations.push({scrollY:window.scrollY,target:m.target.className,added:[...m.addedNodes].map(n=>n.className),attr:m.attributeName,old:m.oldValue})})); obs.observe(document.body,{subtree:true,attributes:true,attributeOldValue:true,childList:true}); // then scroll to each % checkpoint with 600ms settle",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Manual screenshot comparison — misses class toggles and DOM mutations",
+      "warn": "600ms settle time needed after each scroll to let animations complete",
+      "see": ["js-001", "js-003"]
+    },
+    {
+      "id": "js-003",
+      "title": "AVOID: getComputedStyle for animation detection",
+      "tags": ["js", "extraction", "animation", "anti-pattern"],
+      "q": 1,
+      "v": "AVOID",
+      "s": "getComputedStyle returns resolved property values — it NEVER exposes @keyframes definitions, animation timing functions are partially resolved, clip-path values may differ from source.",
+      "p": "// BAD: getComputedStyle(el).animationName → returns name only, not keyframes // BAD: getComputedStyle(el).clipPath → returns computed polygon(), but not the @keyframes that drives it",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Use document.styleSheets iteration (js-001) to get real @keyframes definitions",
+      "see": ["js-001", "js-002"]
+    },
+    {
+      "id": "js-004",
+      "title": "JS library detection before choosing animation strategy",
+      "tags": ["js", "cloning", "gsap", "framer-motion", "animation", "detection"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Always check window.gsap, window.ScrollTrigger, data-framer-component-type before choosing animation implementation. Wrong library choice creates double-animation or no-animation bugs.",
+      "p": "const libs={gsap:!!window.gsap,scrollTrigger:!!window.ScrollTrigger,framer:!!document.querySelector('[data-framer-component-type]'),lottie:!!window.lottie,aos:!!window.AOS}",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Defaulting to IntersectionObserver when GSAP is detected on the source site",
+      "warn": "Site not using GSAP does NOT mean IntersectionObserver is the right choice — read the actual @keyframes first",
+      "see": ["js-001", "js-002", "css-005"]
+    },
+    {
+      "id": "font-001",
+      "title": "Proprietary fonts: extract woff2 from saved site, serve locally",
+      "tags": ["font", "typography", "woff2", "cloning", "font-face"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "When site uses proprietary font (CDN-blocked), extract woff2 files from the saved site's fonts/ directory. Serve via @font-face pointing to public/fonts/. Reference assets only — rewrite content.",
+      "p": "@font-face{font-family:'Clarkson';font-weight:300;font-display:swap;src:url('/fonts/clarkson-300.woff2') format('woff2')}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Trying to load proprietary fonts from CDN — 403 in production",
+      "warn": "Reference assets only — do not redistribute proprietary font files in public projects",
+      "see": []
+    }
+  ]
+}

package/template/.aioson/config.md

@@ -104,34 +104,62 @@ In direct mode (LLM without CLI), agents call them manually following the rules
 When the `aioson` CLI is **not available**, agents must write a devlog file at the end of the session (or when the user asks to save progress). This is the only way to preserve session history for the dashboard when the CLI is missing.
 
 **Directory:** `aioson-logs/` (create if absent)
-**Filename:** `devlog-{YYYY-MM-DD}T{HH-MM}.md`
-**If a devlog from today already exists:** append to it instead of creating a new file.
+**Filename:** `devlog-{agent}-{unix-timestamp}.md`
 
 **Template:**
 ```markdown
 ---
-agent: "{agent-id}"
-session_start: "{ISO 8601}"
-session_end: "{ISO 8601}"
-status: completed # or partial
-summary: "One-line summary of what was accomplished"
+agent: dev
+feature: {feature-slug or "project"}
+session_key: direct-session:{unix-timestamp}:{agent}
+started_at: {ISO 8601}
+finished_at: {ISO 8601}
+status: completed
+verdict: null
+plan_step: null
 ---
 
+# Devlog: @{agent} — {feature} — {YYYY-MM-DD}
+
+## Summary
+{One sentence of what was accomplished.}
+
+## Artifacts
+- {path/to/file.ext}
+
 ## Decisions
 - {decision} → {why}
 
-## Changes
-- {file}: {what changed}
+## Learnings
+- [process] {any process learning from this session}
+- [domain] {any domain learning}
+
+## Blockers
+- {blocker or "None"}
+```
 
-## Next
-- {what should happen next session}
+**Minimum viable devlog (if session was cut short):**
+```markdown
+---
+agent: {agent}
+feature: {slug}
+status: partial
+started_at: {ISO 8601}
+finished_at: {ISO 8601}
+---
+# Devlog: @{agent} — {feature} — {date}
+## Summary
+{one sentence of what was done}
+## Learnings
+- [process] {any process learning}
 ```
 
 **Rules:**
-- Max 30 lines. This is a decision log, not a transcript.
+- Frontmatter fields `agent`, `started_at`, `finished_at` are required. All others are optional.
+- `[process]` / `[domain]` / `[quality]` / `[preference]` prefixes in Learnings enable automatic promotion to project memory.
 - Record **why** decisions were made — the "what" is in the git diff.
 - Skip the devlog for trivial sessions (quick questions, no code changes).
-- When the CLI becomes available, `aioson devlog:sync` will import file-based devlogs into SQLite for the dashboard.
+- When the CLI becomes available: `aioson devlog:process .` imports devlogs into SQLite (learnings, artifacts, decisions, verdict).
 
 ## On-demand context layers
 
@@ -243,6 +271,108 @@ When a workflow stage completes or an agent finishes via `runtime-log --finish`,
 
 Agents can read this file on activation to resume work without losing context between sessions.
 
+## Context compaction template
+
+When approaching context threshold, any agent can write a structured checkpoint to
+`.aioson/context/last-handoff.json` before compacting:
+
+```json
+{
+  "agent": "<agent-name>",
+  "session_summary": {
+    "messages_processed": "<N>",
+    "tools_used": ["<tool1>", "<tool2>"],
+    "recent_requests": ["<last 3 user requests>"],
+    "pending_work": ["<item1>", "<item2>"],
+    "key_files": ["<path1>", "<path2>"],
+    "timeline": ["<step1 done>", "<step2 done>"]
+  },
+  "compacted_at": "<ISO 8601>",
+  "resume_instruction": "Continue from this summary. Do not acknowledge it."
+}
+```
+
+After writing, prepend to the next response:
+`[Context compacted — resuming from checkpoint]`
+
+On resume: read `last-handoff.json` before loading any other context file.
+
+Agents with dedicated compaction protocols (e.g. `@orache`) define additional
+steps in their own files — this template is the shared baseline.
+
+## Hook contract (PreToolUse / PostToolUse)
+
+Hooks are shell scripts configured in `.claude/settings.json` under `hooks`.
+The harness passes context via stdin (JSON) and environment variables.
+
+### Exit codes
+| Code | Meaning |
+|------|---------|
+| 0 | Allow — continue tool execution |
+| 2 | Deny — block tool, return message to agent |
+| other non-zero | Warn — log warning, continue execution |
+
+### Environment variables
+| Variable | Description |
+|----------|-------------|
+| `HOOK_EVENT` | `PreToolUse` or `PostToolUse` |
+| `HOOK_TOOL_NAME` | Tool being executed (e.g. `Bash`, `Write`) |
+| `HOOK_TOOL_INPUT` | JSON params of the tool call |
+| `HOOK_TOOL_IS_ERROR` | `true`/`false` (PostToolUse only) |
+| `HOOK_TOOL_OUTPUT` | Tool output (PostToolUse only) |
+
+### Example: block rm -rf in Bash
+```bash
+#!/bin/bash
+INPUT=$(cat)
+if echo "$INPUT" | grep -q "rm -rf"; then
+  echo "Blocked: rm -rf not allowed in this project"
+  exit 2
+fi
+exit 0
+```
+
+## Agent file size guidelines
+
+The Claude Code harness enforces a hard limit of ~4,000 chars per auto-loaded
+instruction file (`CLAUDE.md` hierarchy). Files are truncated silently.
+Agent files in `.aioson/agents/` are read manually (not auto-loaded) so they
+are not subject to this truncation, but large files consume context budget.
+
+Recommended targets:
+
+| File type | Target | Notes |
+|-----------|--------|-------|
+| `CLAUDE.md` / `AGENTS.md` | ≤ 3,500 chars | Auto-loaded — hard truncation applies |
+| Focused agents (analyst, qa, tester) | ≤ 8,000 chars | Keep lean |
+| Generalist agents (dev, architect) | ≤ 15,000 chars | Move optional sections to `.aioson/docs/` |
+| Orchestrator agents (orchestrator, squad) | ≤ 12,000 chars | Move boilerplate to `.aioson/rules/` |
+
+When an agent file exceeds its target:
+1. Move repeated boilerplate to a shared `.aioson/rules/` file
+2. Split optional sections into `.aioson/docs/` files (loaded on demand)
+3. Use the "On-demand context layers" pattern from this config
+
+## Config tiers
+
+AIOSON supports three config tiers (precedence: local > project > user):
+
+| Tier | Location | Versioned | Purpose |
+|------|----------|-----------|---------|
+| User | `~/.aioson/config.md` | No | Personal defaults (model, locale, thresholds) |
+| Project | `.aioson/config.md` | Yes | Team standards — source of truth |
+| Local | `.aioson/config.local.md` | No | Machine overrides (local paths, env specifics) |
+
+When the same setting exists in multiple tiers, the lower tier wins (local > project > user).
+
+**Current support:**
+- Project tier: fully supported (this file)
+- Local tier: `config.local.md` is the convention — agents can read it if present
+- User tier (`~/.aioson/config.md`): **backlog** — requires CLI support; not yet read automatically
+
+Until the user tier is implemented in the CLI, use `CLAUDE.local.md` for personal
+preferences that should not affect other team members.
+
 ## Agent locale packs
 - Localized agent prompts are stored in `.aioson/locales/<locale>/agents/`.
 - Active runtime prompts are in `.aioson/agents/`.

package/template/.aioson/constitution.md

@@ -0,0 +1,33 @@
+---
+version: 1.0.0
+ratified: 2026-04-04
+last_amended: 2026-04-04
+---
+
+# AIOSON Constitution
+
+> Principles that govern all agents, all classifications, all sessions.
+> Every agent may cite these articles. No agent may override them.
+
+## Article I — Spec First
+Features begin as specifications, not code. Implementation without a spec artifact is exploration, not development.
+
+## Article II — Right-Sized Process
+MICRO, SMALL, and MEDIUM must not receive the same process depth. Applying MEDIUM ceremony to a MICRO project wastes more than it protects.
+
+## Article III — Observable Work
+Important agent actions leave visible artifacts or runtime signals. Work that exists only in conversation history is work that can be lost.
+
+## Article IV — Testable Behavior
+Acceptance criteria must be independently verifiable. "Works correctly" is not a criterion. "Returns 403 when user A accesses user B's resource" is.
+
+## Article V — Clean Handoffs
+Artifacts must be self-contained enough for the next agent to start without re-reading the full discovery chain. If the next agent needs to ask "where do I start?", the handoff failed.
+
+## Article VI — Simplicity Over Ceremony
+Do not add layers, files, or workflows unless they reduce downstream ambiguity. Three similar lines of code is better than a premature abstraction. One well-written spec is better than five thin artifacts.
+
+## Governance
+- Amendments require explicit user approval
+- Articles are numbered, not named — never renumber existing articles
+- New articles are appended, never inserted

package/template/.aioson/context/project-pulse.md

@@ -0,0 +1,34 @@
+---
+updated_at: null
+last_agent: null
+last_gate: null
+active_features: 0
+blocked: false
+blocked_reason: null
+---
+
+# Project Pulse
+
+> Global project state. Updated by every agent at session end.
+> Read this FIRST when starting any session to orient quickly.
+> Max 30 lines of content — trim older entries when growing beyond that.
+
+## Active work
+
+| Feature | Phase | Agent | Status | Last checkpoint |
+|---------|-------|-------|--------|-----------------|
+| — | — | — | — | — |
+
+## Recent activity (last 3 sessions)
+
+| Date | Agent | Action | Result |
+|------|-------|--------|--------|
+| — | — | — | — |
+
+## Blockers
+
+None.
+
+## Next recommended action
+
+No active work. Start with `@product` for a new feature or `@setup` for a new project.

package/template/.aioson/docs/LAYERS.md

@@ -0,0 +1,79 @@
+---
+description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
+agents: []
+---
+
+# AIOSON Project Memory Layers
+
+Three directories accumulate project knowledge over time.
+Each has a different purpose and a different update cadence.
+
+---
+
+## Layer 1 — `.aioson/rules/`
+
+**What it is:** behavioral overrides for agents.
+**Who writes it:** the user, or promoted from recurring @dev patterns.
+**When to use:** when you want to enforce a convention that overrides agent defaults — globally or for specific agents.
+**Cadence:** stable. Rules change rarely; only when a convention is proven wrong or superseded.
+
+Examples of good rules:
+- "All API routes must follow REST naming conventions in this project"
+- "Never use float for monetary values — use integer cents"
+- "The @dev agent must always write a migration for schema changes"
+
+See `rules/README.md` for format and frontmatter reference.
+
+---
+
+## Layer 2 — `.aioson/docs/`
+
+**What it is:** domain knowledge and technical reference that agents load on demand.
+**Who writes it:** the user or @architect, based on real integration and domain complexity.
+**When to use:** when multiple agents across different features need the same external context — API behavior, third-party quirks, data model explanations, integration patterns.
+**Cadence:** updated when the referenced system changes, not after every feature.
+
+Examples of good docs:
+- `stripe-integration-context.md` — describes webhook event model, idempotency keys used
+- `auth-rbac-model.md` — explains the role/permission system as it stands in production
+- `legacy-api-behavior.md` — documents known quirks of an external API affecting multiple features
+
+See `docs/README.md` for format and naming conventions.
+
+---
+
+## Layer 3 — `.aioson/context/design-doc*.md`
+
+**What it is:** living decision document for the current feature or project scope.
+**Who writes it:** @discovery-design-doc.
+**Who updates it:** @dev at feature close, @discovery-design-doc when resuming.
+**When to use:** automatically — one per feature (`design-doc-{slug}.md`) or one project-wide (`design-doc.md`).
+**Cadence:** updated at the end of each feature implementation session. Decisions are append-only — never deleted.
+
+---
+
+## Decision Guide
+
+| Situation | Where it goes |
+|-----------|--------------|
+| Enforce a coding convention for this project | `rules/` |
+| Agents must always know about an external API behavior | `docs/` |
+| Document the scope and decisions for a specific feature | `design-doc-{slug}.md` |
+| Log a global project-wide architecture decision | `design-doc.md` |
+| Promote a recurring @dev pattern | `rules/` via @dev promotion |
+| Document an integration used by 3+ features | `docs/` |
+| Record what was decided during a single feature session | `design-doc-{slug}.md` (Decisions already made section) |
+
+---
+
+## What NOT to put in these layers
+
+| Content | Where it actually belongs |
+|---------|--------------------------|
+| Feature requirements | `requirements-{slug}.md` |
+| PRD / product scope | `prd-{slug}.md` |
+| Execution sequence | `implementation-plan-{slug}.md` |
+| Current implementation state | `spec-{slug}.md` |
+| Project-wide context | `project.context.md` |
+| Domain entity map | `discovery.md` |
+| Technical architecture | `architecture.md` |

package/template/.aioson/docs/README.md

@@ -0,0 +1,76 @@
+---
+description: "Guide to the docs layer: domain knowledge and technical reference for agents"
+agents: []
+---
+
+# Project Docs
+
+Files in this directory are domain knowledge and technical reference that agents load on demand.
+
+Unlike `rules/` (which enforce conventions), docs explain **how something works** — external APIs, data models, integration patterns, legacy behavior, third-party quirks.
+
+---
+
+## Frontmatter Format
+
+```yaml
+---
+description: "Short description of what this doc covers — used by agents to decide relevance"
+scope: "global"       # or a feature slug if doc is scoped to one area
+agents: []            # empty = any agent may load; or restrict: [dev, architect]
+---
+```
+
+---
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | yes | What this doc covers — agents use this to decide whether to load it |
+| `scope` | no | `global` (default) or a feature slug for narrow scope |
+| `agents` | no | If empty, any agent may load; if listed, only those agents load it |
+
+---
+
+## Loading Behavior
+
+Agents load docs when the `description` frontmatter is relevant to the current task.
+An empty `agents:` field means any agent can load the doc.
+Docs are loaded in addition to the current context — not as replacements.
+
+---
+
+## When to Create a Doc
+
+Create a doc when:
+- Two or more features need the same external context
+- An integration has non-obvious behavior that has caused bugs or would cause rework
+- A data model exists only in production and is not derivable from the codebase
+- A third-party API has quirks that affect how agents implement against it
+
+Do NOT create a doc for:
+- Feature-specific decisions (use `design-doc-{slug}.md` instead)
+- Project conventions (use `rules/` instead)
+- Current implementation state (use `spec-{slug}.md` instead)
+
+---
+
+## Naming Convention
+
+Use kebab-case. Name the file after the system or concept, not the feature:
+
+| Good | Bad |
+|------|-----|
+| `stripe-webhook-behavior.md` | `billing-feature-notes.md` |
+| `auth-rbac-model.md` | `auth-stuff.md` |
+| `legacy-api-quirks.md` | `misc-notes.md` |
+| `email-delivery-constraints.md` | `sendgrid.md` (too generic) |
+
+---
+
+## Example
+
+See `example-external-api-context.md` in this directory for a working template.
+
+For the layer separation guide (when to use `docs/` vs `rules/` vs `design-doc`), see `LAYERS.md`.