@jaimevalasek/aioson 1.7.2 → 1.9.0

package/docs/en/3-recipes/from-idea-to-prd-via-briefing.md

@@ -0,0 +1,235 @@
+# Recipe: From idea to PRD via `@briefing`
+
+> **Who this is for:** anyone with a vague idea — phone notes, Notion draft, informal meeting conversation.
+> **Time to run:** 30 to 90 min (depends on how much material you already have).
+> **What you'll have at the end:** a PRD generated by `@product` based on an enriched briefing — no obvious gaps, risks mapped.
+
+---
+
+## The problem this recipe solves
+
+You went straight to `@product` with a vague idea and heard:
+
+> "Before creating a PRD, I need to understand the problem better. What is the main use case?"
+
+This question loop happens because the idea has no shape yet. `@briefing` exists exactly for this step: it structures what exists before the PRD, so that `@product` arrives at the conversation with a solid foundation.
+
+---
+
+## The trail in one line
+
+```
+vague idea / notes
+       ↓
+   @briefing   →  .aioson/briefings/{slug}/briefings.md
+       ↓
+aioson briefing:approve
+       ↓
+   @product   →  prd.md (or prd-{slug}.md)
+       ↓
+ (optional) @sheldon  →  enrichment + phased plan
+```
+
+---
+
+## Variant A — You already have drafts in `plans/`
+
+This is the most common case: you researched, copied text, wrote ideas, and now have loose files.
+
+### Step 1 — Put the material in `plans/`
+
+```bash
+# Files at the project root (gitignored by default)
+plans/
+├── idea-notifications.md     ← idea sketch
+├── firebase-research.md      ← technical research you did
+└── competitor-benchmark.md   ← analysis you copied from another chat
+```
+
+> `plans/` is **read-only for agents** — they read but never modify. Your files stay intact.
+> See [External plans for @product](./external-plans-for-product.md) for details on this flow.
+
+### Step 2 — Activate `@briefing`
+
+```
+You > @briefing
+
+@briefing > Found 3 files in plans/:
+             - plans/idea-notifications.md
+             - plans/firebase-research.md
+             - plans/competitor-benchmark.md
+
+             Which ones should I use as source? (all or specific list)
+You > All.
+
+@briefing > Reading and enriching...
+             Validating technical assumptions about Firebase push...
+
+             Briefing generated: .aioson/briefings/push-notifications/briefings.md
+
+             Summary:
+             - Problem: users miss important events due to missing push
+             - Validated hypotheses: 3/4
+             - Gap found: maximum notification frequency not defined
+             - Risk: Firebase rate limit on free plan (5,000/day)
+             - Next step: approval via CLI → @product
+
+             The briefing is ready. Do you want to adjust anything before approving?
+```
+
+**What was saved on disk:**
+```
+.aioson/briefings/push-notifications/
+└── briefings.md    ← problem, hypotheses, gaps, risks, open questions
+.aioson/briefings/
+└── config.md       ← index of all briefings (status: draft)
+```
+
+### Step 3 — Review and approve
+
+Read `.aioson/briefings/push-notifications/briefings.md`. If it looks good:
+
+```bash
+aioson briefing:approve
+# or specify the slug:
+aioson briefing:approve --slug=push-notifications
+```
+
+Status changes from `draft` to `approved`. `@product` detects this automatically.
+
+### Step 4 — Activate `@product`
+
+```
+You > @product
+
+@product > Detected approved briefing: push-notifications (created today).
+            Can I use it as the base for this feature's PRD?
+You > Yes.
+
+@product > [reads briefing, asks questions only about what is missing]
+            What is the feature slug?
+You > push-notifications
+
+@product > Main ACs I will include in the PRD:
+            1. User receives push within ≤ 2s after event
+            2. Rate limit respected (1 notification/min per user)
+            3. Opt-out via settings (GDPR)
+
+            Out of scope: email notifications (briefing flagged for phase 2).
+
+            PRD created: .aioson/context/prd-push-notifications.md
+            Next: @sheldon (recommended — there is 1 open technical risk in the briefing).
+```
+
+---
+
+## Variant B — The idea is only in your head (conversational mode)
+
+No files. No drafts. Just a desire to build something. When `plans/` is empty, `@briefing` enters **structured conversational mode** — a 6-step interview that builds the briefing question by question.
+
+```
+You > @briefing
+
+@briefing > I didn't find any files in plans/. Would you like to plan
+            the idea with me conversationally? I'll ask questions and
+            build the briefing from your answers.
+You > Yes.
+
+─── Step A — Context (the "why now?") ───
+@briefing > Tell me about the context: what is the current situation and
+            what changed recently that made this surface today? A trigger
+            always exists.
+You > Customers are complaining they miss order updates.
+      We had 3 support tickets last week.
+
+─── Step B — Problem (JTBD framing) ───
+@briefing > What specific pain point do you want to solve? For whom?
+            What can't they accomplish today without working around it?
+You > Customer places an order, closes the app, and has no idea if it was confirmed.
+
+@briefing > Let me reframe as JTBD: "When I place an order and close
+            the app, I want to know it was confirmed, so I don't have
+            to go back and check." Does that fit?
+You > Yes, exactly.
+
+─── Step C — Proposed solution ───
+@briefing > What directions are you considering? Multiple is fine —
+            this is hypothesis, not commitment.
+You > Push notification. Maybe SMS for orders above $500.
+
+─── Step D — Risks (Cagan's four + cost of not acting) ───
+@briefing > I'll ask in 4 passes:
+            1. Value: will users want it? (or just tolerate it?)
+            2. Usability: will they understand and configure it?
+            3. Feasibility: can we build it?
+            4. Viability: legal/compliance/cost/brand?
+            And finally: what is the cost of NOT doing it?
+You > [answers each one]
+
+─── Step E — Gaps (current state vs desired state) ───
+@briefing > For each undefined thing, let's frame it as:
+            "today we have X, we want Y, the delta is Z (measurable when possible)".
+            What is still open?
+You > Maximum notification frequency per day. Today: undefined. We want: ?
+
+─── Step F — Classify open questions ───
+@briefing > I'll tag each question with one of:
+            [research-able]      → < 4h of digging resolves it
+            [testable]           → 1-2 day experiment
+            [decision-required]  → judgment call between alternatives
+            [out-of-scope]       → park it, doesn't block
+
+            Result:
+            1. Maximum frequency          [decision-required]
+            2. Expected real engagement   [research-able]
+            3. SMS for high-value orders  [out-of-scope — phase 2]
+
+@briefing > 6 steps complete. Briefing generated:
+            .aioson/briefings/order-notifications/briefings.md
+```
+
+> **Quality rule:** if more than 3 questions remain as `decision-required` or vague, `@briefing` does another round before writing. A rushed briefing is expensive later.
+
+The rest of the flow is the same: approve via CLI → `@product`.
+
+---
+
+## What `@briefing` catches that `@product` wouldn't
+
+| What it identifies | Example |
+|---|---|
+| Unvalidated market hypotheses | "Will users use push?" — it researches engagement data |
+| Technical risks in the plan | Rate limits, latencies, volume costs |
+| Scope gaps | Maximum notification frequency not defined |
+| Internal contradictions | Draft says "real-time" but research shows prohibitive cost |
+| Open decisions blocking the PRD | "Firebase or native APNS?" needs to be resolved first |
+
+---
+
+## When to skip `@briefing`
+
+- Simple and clear feature: MICRO, no ambiguity — go straight to `@product`.
+- You already have an enriched PRD — use `@sheldon` to refine it.
+- It is a continuation of an already started feature — use `@deyvin`.
+
+---
+
+## Files created by this recipe
+
+```
+plans/                              ← your drafts (untouched)
+.aioson/briefings/{slug}/
+├── briefings.md                    ← @briefing output
+└── {specific-theme}.md             ← (optional) complex themes
+.aioson/briefings/config.md         ← briefings index
+.aioson/context/prd-{slug}.md       ← @product output
+```
+
+---
+
+## Next steps
+
+- [External plans for @product](./external-plans-for-product.md) — how to use ChatGPT/Claude.ai output as source for `plans/`
+- [Full feature with @sheldon](./full-feature-with-sheldon.md) — when the PRD is ready and the trail is SMALL/MEDIUM
+- [@briefing — agent sheet](../4-agents/briefing.md) — technical reference for the agent
+- [@product — agent sheet](../4-agents/product.md) — technical reference for the agent

package/docs/en/3-recipes/full-feature-with-sheldon.md

@@ -0,0 +1,338 @@
+# Recipe: Full feature with `@sheldon` (canonical trail)
+
+> **Who this is for:** medium-to-high complexity features where wrong early decisions are costly.
+> **Time to run:** 2 to 8 hours (varies with scope), spread across 1–4 sessions.
+> **What you'll have at the end:** a feature implemented, tested, security-audited, and reviewed end-to-end — every decision traceable on disk.
+> **Status:** this is the trail the AIOSON creator uses by default for SMALL/MEDIUM projects with significant implementation.
+
+---
+
+## The trail in one line
+
+```
+@product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev
+                                                              │
+                                              (@qa ↔ @dev)  ← autonomous loop
+                                                              │
+                              optional: @tester → (@qa ↔ @dev) ← extra coverage
+                                                              │
+                              optional: @pentester ↔ @dev    ← security
+                                                              │
+                                              @qa (final general review)
+```
+
+**Why order matters:** each agent reads the artifacts left by the previous one. Skipping an agent means the next one improvises — and improvisation on big decisions becomes rework.
+
+---
+
+## Scenario
+
+You are building a meaningful feature — typical examples: **subscription billing with Stripe**, **seller dashboard in a marketplace**, **order cancellation with time-window rules**. Something that mixes backend + UI + business rules + external integration.
+
+If the feature is trivial (simple CRUD without business logic), skip to the [Landing page recipe](./landing-page.md) or [SaaS app from scratch](./saas-app-from-scratch.md). This trail is a cannon; don't use it to shoot sparrows.
+
+## Prerequisites
+
+- Project with `aioson init/install` already run
+- `project.context.md` populated (`@setup` already done)
+- Classification **SMALL** or **MEDIUM**
+- AI client open in the project
+
+---
+
+## Step 1 — `@product` defines the PRD
+
+```
+You > @product
+
+@product > Let's define a feature. What's the slug?
+You > billing-subscription
+
+@product > In one sentence, the problem?
+You > Customer wants to subscribe to monthly/annual plan and manage payment
+
+@product > [guided questions: ACs, out-of-scope, dependencies, SLA limits]
+@product > PRD created at .aioson/context/prd.md (copy at features/billing-subscription/spec.md).
+@product > Next: @sheldon to validate and enrich before going technical.
+```
+
+**What was left on disk:** `prd.md` with clear sections (problem, scope, ACs, out-of-scope).
+
+> **Variation:** if you already have material in `/plans/` or an approved briefing, `@product` detects it and offers to use it as a base. See [External plans for @product](./external-plans-for-product.md) and [From idea to PRD via @briefing](./from-idea-to-prd-via-briefing.md).
+
+---
+
+## Step 2 — `@sheldon` enriches the PRD (critical step)
+
+This is the step most people skip — and where AIOSON gains depth.
+
+```
+You > @sheldon
+
+@sheldon > Reading prd.md... scanning .aioson/context/architecture.md, dependencies, plans/.
+@sheldon > Detected 4 gaps:
+        1. PRD does not cover plan downgrade (only upgrade)
+        2. No decision on proportional billing (proration)
+        3. Stripe webhook has no retry/idempotency policy
+        4. No ACs for billing failure after 3 attempts (dunning)
+
+@sheldon > Do you have external sources? [URL, local file, "no"]
+You > docs.stripe.com/billing/subscriptions/upgrade-downgrade
+
+@sheldon > [searches, reads, cites]
+@sheldon > Recommendation:
+        - Enrich PRD in-place (gaps 1, 2 are product decisions)
+        - Create phased plan at .aioson/plans/billing-subscription/ for
+          phased implementation of webhook+dunning (gaps 3, 4)
+
+@sheldon > Applying enrichment... prd.md updated.
+@sheldon > Phased plan: .aioson/plans/billing-subscription/{phase-1.md, phase-2.md, harness-contract.json}
+@sheldon > Next: @analyst.
+```
+
+**Why run `@sheldon`:**
+- It reads the **actual project code** and cross-references it with the PRD — it sees what's missing.
+- It can fetch **external sources** (Stripe docs, RFCs, technical posts) and **cite them**.
+- It decides between **enriching in-place** (editing `prd.md`) or **creating a phased plan** when scope is too large for a single implementation.
+
+**Can run multiple times:** if the first pass left gaps, invoke `@sheldon` again. It detects existing `sheldon-enrichment.md` and offers a new enrichment round without starting over.
+
+> **When NOT to run `@sheldon`:** trivial features (basic CRUD) or MICRO. The enrichment effort does not pay off.
+
+---
+
+## Step 3 — `@analyst` maps the domain
+
+```
+You > @analyst
+
+@analyst > Reading enriched prd.md + codebase.
+@analyst > Entities: Subscription, Plan, Invoice, PaymentMethod, DunningAttempt.
+        Already exist in code: Customer, Order. Will extend.
+@analyst > Domain map saved to architecture.md (domain section).
+@analyst > Next: @architect.
+```
+
+## Step 4 — `@architect` decides the technical structure
+
+```
+You > @architect
+
+@architect > Decisions:
+        - Stripe Customer Portal for self-service (reduces custom UI)
+        - Webhook handler on dedicated route with idempotency key
+        - Daily dunning cron (3 attempts, 1d/3d/7d intervals)
+        - Migration: subscriptions table with FK on customers
+@architect > Decisions saved to architecture.md (decisions section).
+@architect > Next: @ux-ui.
+```
+
+## Step 5 — `@ux-ui` designs the UI
+
+```
+You > @ux-ui
+
+@ux-ui > Reading architecture and PRD. Stack confirmed: React + current design skill.
+@ux-ui > Components:
+        - PlanSelector (3 cards: Free, Pro, Enterprise)
+        - BillingPortal (link to Stripe Portal)
+        - InvoiceList
+        - DunningBanner (failed billing alert)
+@ux-ui > Specs saved to design-doc.md. Next: @pm.
+```
+
+> In **SMALL** projects without `@ux-ui` in the flow, skip this step.
+
+## Step 6 — `@pm` breaks down into user stories
+
+```
+You > @pm
+
+@pm > 7 user stories identified, grouped into 3 epics.
+        Each with verifiable ACs (e.g., "POST /subscriptions/upgrade
+        returns 200 and sets proration_amount > 0").
+@pm > tasks.md saved.
+@pm > Next: @orchestrator.
+```
+
+## Step 7 — `@orchestrator` defines parallel lanes
+
+```
+You > @orchestrator
+
+@orchestrator > Identified 3 parallelizable lanes:
+        - lane-backend.md (routes + webhook + cron)
+        - lane-ui.md (4 components + integration)
+        - lane-migration.md (DB schema + test seeds)
+@orchestrator > Dependency: lane-ui depends on lane-backend for the API contract.
+@orchestrator > parallel/ saved. harness-contract.json created.
+@orchestrator > Next: @dev (can work lanes in separate sessions).
+```
+
+> In **SMALL** projects, skip `@orchestrator` — no parallel lanes worth the overhead.
+
+## Step 8 — `@dev` implements
+
+```
+You > @dev
+
+@dev > Reading full plan. Starting with lane-backend (no dependencies).
+@dev > [implements] Lane-backend done. dev-state.md updated.
+@dev > Next: run @qa for this lane before moving to lane-ui.
+```
+
+> `@dev` is **resumable**. If the session drops midway, next session `@deyvin` reads `dev-state.md` and continues exactly where it left off. See [Continuity between sessions](./continuity-between-sessions.md).
+
+## Step 9 — `@qa ↔ @dev` loop (autonomous, cap 2)
+
+```
+You > @qa
+
+@qa > 18 ACs identified. Writing tests...
+@qa > Failure on AC-12 (proration calculation).
+        Iteration 1/2 — passing to @dev autonomously.
+@dev > [fixes calculation, renames misleading variable]
+@qa > Re-running... 18/18 OK.
+@qa > test-plan.md and qa-report.md saved.
+```
+
+**Cap 2** means: the autonomous loop runs at most 2 iterations. If it still fails, `@qa` stops and calls you for human review — prevents infinite loops.
+
+---
+
+## Step 10 (optional) — `@tester` for systematic coverage
+
+When to activate:
+- You know the feature will have high load and want **more coverage** than just the PRD ACs.
+- You suspect **edge cases** that `@qa` didn't cover (timezones, concurrency, locales).
+- The project is legacy and the feature touches untested code.
+
+```
+You > @tester
+
+@tester > Reading qa-report. Current coverage: 78%. Quality tier: MEDIUM.
+@tester > Identified 3 zones with test smell:
+        - Tests coupled to brittle fixtures (3 tests)
+        - 2 tests only verify "no throw" (don't check behavior)
+        - Missing proration coverage on edge dates (29th–31st of month)
+@tester > Additional test plan saved to test-inventory.md.
+@tester > Next: run @qa again to implement missing tests.
+```
+
+After `@tester`, **run `@qa` again** — the `@qa ↔ @dev` loop repeats on the new tests.
+
+## Step 11 (optional) — `@pentester ↔ @dev` for security
+
+When to activate:
+- Feature touches sensitive data (payment, PII, auth).
+- Going to production.
+- There is a regulatory requirement.
+
+```
+You > @pentester
+
+@pentester > Mapping attack surfaces (OWASP + supply chain + tooling).
+@pentester > Findings:
+        - HIGH: Stripe webhook without signature validation in dev mode
+        - MEDIUM: /billing/portal route without rate-limit
+        - LOW: log includes customer email in plaintext
+
+@pentester > Iteration 1 — passing to @dev to fix.
+@dev > [fixes signature validation, adds rate-limit, redacts log]
+@pentester > Re-scan: HIGH=0, MEDIUM=0, LOW=1 (accepted as low risk).
+@pentester > security-findings-billing-subscription.json saved.
+```
+
+## Step 12 — Final `@qa`, general review
+
+After everything (tester and pentester), run `@qa` one more time:
+
+```
+You > @qa
+
+@qa > General review post-pentester and post-tester.
+@qa > 18 original ACs + 9 additional tests (from @tester) + 3 security
+        regression tests (from @pentester). Total: 30 tests. All passing.
+@qa > Verdict: feature ready. @validator recommended before closing.
+```
+
+Optional: run `@validator` to check the success contract, and `@committer` for the final commit.
+
+---
+
+## What was left on disk (full audit trail)
+
+```
+.aioson/context/
+├── prd.md                             ← @product
+├── sheldon-enrichment.md              ← @sheldon (multiple rounds)
+├── architecture.md                    ← @analyst + @architect
+├── design-doc.md                      ← @ux-ui
+├── tasks.md                           ← @pm
+├── parallel/
+│   ├── lane-backend.md                ← @orchestrator
+│   ├── lane-ui.md
+│   └── lane-migration.md
+├── dev-state.md                       ← @dev (updated each session)
+├── test-plan.md                       ← @qa
+├── qa-report-billing-subscription.md  ← @qa
+├── test-inventory.md                  ← @tester
+├── security-findings-billing-subscription.json ← @pentester
+└── features/billing-subscription/
+    ├── spec.md
+    └── done/                          ← archived by feature:close
+
+.aioson/plans/billing-subscription/
+├── phase-1.md                         ← @sheldon (phased plan)
+├── phase-2.md
+├── harness-contract.json              ← success contract
+└── progress.json                      ← current status
+```
+
+Six months from now, anyone (or any AI) reads these files and understands **everything**: what was planned, why, what was implemented, what was discarded.
+
+---
+
+## Trail variations
+
+### MICRO (small scope)
+`@product → @dev → @qa`. Skip `@sheldon`, `@analyst`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`. The Constitution Article II (*Right-Sized Process*) protects you from unnecessary ceremony.
+
+### SMALL without UI
+`@product → @sheldon → @analyst → @architect → @dev → @qa`. Skip `@ux-ui`, `@pm`, `@orchestrator`.
+
+### Full MEDIUM
+The complete trail above.
+
+### When you are only implementing Lane 1 today
+Go through `@orchestrator`, then invoke `@dev` only for `lane-backend.md`. Pause before `@qa`. Next session: `@deyvin` picks up on the pending lane.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `@sheldon` complains the PRD is vague | Go back to `@product` and refine. `@sheldon` does not invent what is not clear. |
+| `@orchestrator` creates only 1 lane | Your feature is probably SMALL in disguise. Skip parallel lanes. |
+| `@qa ↔ @dev` loop hit cap 2 | There is a design defect. Return to `@architect` or `@product` before writing more code. |
+| `@pentester` HIGH finding won't clear | Don't force it. Document as accepted risk or defer the feature. |
+| Session dropped mid-`@dev` | `@deyvin` picks up. See [Continuity between sessions](./continuity-between-sessions.md). |
+
+---
+
+## When NOT to use this trail
+
+- **Isolated bug fix** — go straight to `@dev` (with bug ID reference) and `@qa`.
+- **Refactor without behavior change** — use [Large refactor](./large-refactor.md).
+- **MICRO feature without new business logic** — overhead not worth it.
+
+---
+
+## Next step
+
+- [SDD: plans and structure](../5-reference/sdd-planos-e-estrutura.md) — deep dive into the structure `@pm` and `@orchestrator` create
+- [From idea to PRD via @briefing](./from-idea-to-prd-via-briefing.md) — when the idea is still vague
+- [External plans for @product](./external-plans-for-product.md) — when you already planned in another chat
+- [Continuity between sessions](./continuity-between-sessions.md) — to resume the trail in another session
+- [Ecosystem map](../1-understand/ecosystem-map.md) — view all agents

package/docs/en/4-agents/README.md

@@ -0,0 +1,56 @@
+# Agent cards — AIOSON (EN)
+
+This layer will hold one card per AIOSON agent (28 total), translated from [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md).
+
+Cards are being translated progressively. Until a card is available here, the PT version is the canonical reference — it follows the same format and covers the same agents.
+
+---
+
+## The 28 agents
+
+### Workflow core (pipeline order)
+
+| Agent | Role |
+|---|---|
+| `@setup` | Project onboarding — detect stack, classify MICRO/SMALL/MEDIUM, write `project.context.md` |
+| `@briefing` | Pre-PRD framing — turn `plans/` sketches into structured briefings with gap analysis |
+| `@product` | PRD — vision, problem, users, scope, acceptance criteria |
+| `@sheldon` | PRD quality guardian — gap detection, web research, sizing, in-place enrichment or phased plan |
+| `@analyst` | Domain discovery — entities, flows, brownfield mapping |
+| `@architect` | Technical decisions — structure, libraries, integration boundaries |
+| `@ux-ui` | Design system and UI component specs (MEDIUM) |
+| `@pm` | Backlog and user stories (MEDIUM) |
+| `@orchestrator` | Parallel lane coordination (MEDIUM) |
+| `@dev` | Feature implementation — any stack |
+| `@qa` | Risk-first review, test generation, autonomous fix/test loop |
+| `@validator` | Binary contract verification against `harness-contract.json` |
+| `@tester` | Systematic test engineering — legacy and coverage gaps |
+| `@pentester` | Adversarial security review — OWASP Top 10, LLM Top 10, supply chain |
+
+### Continuity & delivery
+
+| Agent | Role |
+|---|---|
+| `@deyvin` (alias `@pair`) | Continuity-first pair — recovers state with `confirmed/inferred`, small validated batches |
+| `@committer` | Professional Git commit message generation |
+| `@discover` | Semantic project cache — `bootstrap/` (structured) and `brains/` (Zettelkasten) |
+| `@neo` | Session router — "I don't know what to do next" |
+
+### Specializations
+
+| Agent | Role |
+|---|---|
+| `@squad` | Create and manage custom multi-agent squads |
+| `@genome` | Create and apply cognitive genomes (domain, function, persona, hybrid) |
+| `@profiler-researcher` | Collect raw material on a public person |
+| `@profiler-enricher` | Cognitive analysis — DISC, Enneagram, Big Five, MBTI |
+| `@profiler-forge` | Generate Genome 3.0+ persona advisor |
+| `@site-forge` | Clone, extract, and forge design skills from any URL |
+| `@design-hybrid-forge` | Combine two design skills into a hybrid |
+| `@orache` | Domain investigation and strategic research |
+| `@copywriter` | Conversion copy — landing pages, VSL scripts |
+| `@discovery-design-doc` | Combined discovery + design doc generation |
+
+---
+
+Full PT cards with dialogue examples, disk outputs, and handoff maps: [`docs/pt/4-agentes/`](../../pt/4-agentes/README.md)

package/docs/en/5-reference/README.md

@@ -0,0 +1,60 @@
+# Technical reference — AIOSON (EN)
+
+> This folder contains technical reference documentation for CLI commands, features, and integrations.
+> **Starting from scratch?** Go to [`2-start/`](../2-start/first-project.md) (in progress — translated from PT).
+> **Want a worked recipe?** Go to [`3-recipes/`](../3-recipes/README.md).
+
+This layer currently holds the original EN feature guides. Additional reference docs (feature-dossier, agent-chain-continuity, sdd-framework, live-sessions, secure-by-default, aioson-com-store, and the full set from `docs/pt/5-referencia/`) will be progressively added as the PT documentation is translated.
+
+---
+
+## CLI & automation
+
+| Document | Description |
+|---|---|
+| [cli-reference.md](./cli-reference.md) | Full reference for every CLI command |
+| [json-schemas.md](./json-schemas.md) | `--json` output contracts for all commands |
+
+---
+
+## Features
+
+| Document | Description |
+|---|---|
+| [mcp.md](./mcp.md) | MCP setup: `mcp:init`, `mcp:doctor`, Context7 and Database connectors |
+| [parallel.md](./parallel.md) | Parallel orchestration: `parallel:init`, `parallel:assign`, lanes, merge |
+| [qa-browser.md](./qa-browser.md) | Browser QA with Playwright: `qa:run`, `qa:scan`, personas |
+| [squad-dashboard.md](./squad-dashboard.md) | Real-time squad monitoring panel |
+
+---
+
+## Internationalization
+
+| Document | Description |
+|---|---|
+| [i18n.md](./i18n.md) | Adding locales, `i18n:add`, `locale:apply`, built-in locales |
+
+---
+
+## Web3
+
+| Document | Description |
+|---|---|
+| [web3.md](./web3.md) | Web3 support: Ethereum (Hardhat/Foundry), Solana (Anchor), Cardano (Aiken) |
+
+---
+
+## Release engineering
+
+| Document | Description |
+|---|---|
+| [release.md](./release.md) | Release process and versioning |
+| [release-flow.md](./release-flow.md) | CI/CD release flow |
+| [release-notes-template.md](./release-notes-template.md) | Template for writing release notes |
+
+---
+
+## Coming from docs/pt/5-referencia/
+
+The following docs exist in PT and will be translated progressively:
+`feature-dossier` · `agent-chain-continuity` · `sdd-framework` · `live-sessions` · `secure-by-default` · `aioson-com-store` · `memoria-e-contexto` · `runtime-observability` · `hooks-session-guard` · `fluxo-artefatos` · `feature-archive` · `design-docs-governance` · `sandbox` · `agent-sharding` · `output-strategy-delivery` · `genome-distribution` · `clientes-ai` · `sdd-planos-e-estrutura`