@jaimevalasek/aioson 1.8.0 → 1.9.0

package/docs/en/1-understand/ecosystem-map.md

@@ -0,0 +1,228 @@
+# AIOSON Ecosystem Map
+
+> **Who this is for:** anyone who wants to see the full team at once.
+> **Reading time:** 8 min
+> **What you'll know after:** who the 28 agents are, when each one enters, and how they communicate.
+
+---
+
+## High-level overview
+
+```
+                       ┌──────────────────┐
+                       │   You + AI       │
+                       │   client         │
+                       └────────┬─────────┘
+                                │
+                ┌───────────────┼───────────────┐
+                ▼               ▼               ▼
+         ┌──────────┐    ┌──────────┐    ┌──────────┐
+         │  Setup   │    │   Neo    │    │ Briefing │
+         │  (boot)  │    │ (route)  │    │ (pre-PRD)│
+         └────┬─────┘    └────┬─────┘    └────┬─────┘
+              │               │               │
+              └───────┬───────┴───────┬───────┘
+                      │               │
+                      ▼               ▼
+        ┌──────────────────────────────────────┐
+        │         DEVELOPMENT CORE             │
+        │                                      │
+        │  Product → Sheldon → Analyst →       │
+        │  Architect → UX-UI → PM →            │
+        │  Orchestrator → Dev → QA →           │
+        │  Validator → Tester → Pentester      │
+        │                                      │
+        └──────────────────────────────────────┘
+                      │
+                      ▼
+        ┌──────────────────────────────────────┐
+        │        CONTINUITY & DELIVERY         │
+        │                                      │
+        │  Deyvin (pair) · Committer (git)     │
+        │  Discover (semantic cache)           │
+        │                                      │
+        └──────────────────────────────────────┘
+                      │
+                      ▼
+        ┌──────────────────────────────────────┐
+        │           SPECIALIZATIONS            │
+        │                                      │
+        │  Squad · Genome · Profiler trio ·    │
+        │  Site-Forge · Design-Hybrid-Forge ·  │
+        │  Orache · Copywriter                 │
+        │                                      │
+        └──────────────────────────────────────┘
+```
+
+---
+
+## Agents grouped by role
+
+### 1. Boot and routing
+
+| Agent | What it does | When to invoke |
+|---|---|---|
+| **`@setup`** | Project onboarding: detects stack, classifies MICRO/SMALL/MEDIUM, writes `project.context.md` | Always first on a new project |
+| **`@neo`** | Reads state and suggests the next agent | When you don't know what to do next |
+| **`@briefing`** | Turns plans/loose notes into a pre-PRD briefing | You have ideas but no feature yet |
+
+### 2. Development core (official workflow)
+
+The default order depends on the classification:
+
+**MICRO:** `@setup → @product (optional) → @dev`
+**SMALL:** `@setup → @product → @sheldon (optional) → @analyst → @architect → @dev → @qa`
+**MEDIUM:** `@setup → @product → @sheldon → @analyst → @architect → @ux-ui → @pm → @orchestrator → @dev → @qa`
+
+> **Why does `@sheldon` appear so early?** It is the **PRD quality guardian** — it runs *between* `@product` and `@analyst` to detect gaps, validate technical assumptions with web research, and decide between enriching the PRD in-place or creating a phased plan in `.aioson/plans/{slug}/`. Can be invoked N times on the same PRD. Skipping this step on serious features is expensive later.
+
+| Agent | What it does | Main output |
+|---|---|---|
+| **`@product`** | Defines vision, scope, feature PRD | `prd.md`, `spec.md` |
+| **`@sheldon`** | PRD quality guardian — gap analysis, web research, sizing, decides in-place vs phased plan | `sheldon-enrichment-{slug}.md` or `.aioson/plans/{slug}/` |
+| **`@analyst`** | Discovers domain, entities, flows in the codebase | `architecture.md`, ER diagrams |
+| **`@architect`** | Technical decisions: structure, libs, integrations | `architecture.md` (decisions) |
+| **`@ux-ui`** | Design system and component specs (MEDIUM) | `design-doc.md`, `discovery.md` |
+| **`@pm`** | Backlog, user stories, ACs (MEDIUM) | `tasks.md`, user stories |
+| **`@orchestrator`** | Coordinates parallel lanes (MEDIUM) | `parallel/`, execution plan |
+| **`@dev`** | Implements the feature | Code + `dev-state.md` |
+| **`@qa`** | Writes tests, validates ACs, autonomous fix cycle (cap 2) | `test-plan.md`, `qa-report-*.md` |
+| **`@validator`** | Technically validates against `harness-contract.json` in a context sandbox | `.aioson/plans/{slug}/last-validator-output.json` (consumed by `harness:apply-validation`, updates `progress.json`) |
+| **`@tester`** | Systematic test engineering (legacy/brownfield) | `test-inventory.md`, coverage tier |
+| **`@pentester`** | Adversarial security review (OWASP, LLM Top 10) | `security-findings-*.json` |
+
+### 3. Continuity and delivery
+
+| Agent | What it does | When to invoke |
+|---|---|---|
+| **`@deyvin`** (alias `@pair`) | Continuity-first pair programming — recovers state with `confirmed/inferred`, works in small validated batches, automatic scope gate (refuses greenfield and hands back to `@product`) | Resuming a feature after a crash, debugging a small slice, pairing on a known task |
+| **`@committer`** | Generates professional commit messages | Before committing |
+| **`@discover`** | Builds a semantic cache of the project: produces `bootstrap/` (structured by artifact type, for agents to read) **and** `brains/` (Zettelkasten for cross-reference) | Fast onboarding on a large codebase |
+
+### 4. Specializations
+
+| Agent | What it does |
+|---|---|
+| **`@squad`** | Creates/manages custom squads (`refresh`, `agent-create`) |
+| **`@genome`** | Creates and applies genomes (cognitive DNA of personas) |
+| **`@profiler-researcher`** | Collects raw material about a public figure |
+| **`@profiler-enricher`** | Analyzes the material cognitively |
+| **`@profiler-forge`** | Generates Genome 4.0 + advisor |
+| **`@site-forge`** | Clones, rebuilds, or extracts design from any URL |
+| **`@design-hybrid-forge`** | Combines two design skills into a hybrid |
+| **`@orache`** | Domain investigation and strategic research |
+| **`@copywriter`** | Conversion copy for landing pages, emails |
+| **`@discovery-design-doc`** | Discovery + design doc combined (joint mode) |
+
+---
+
+## How agents "talk"
+
+They **don't talk to each other directly**. They talk **through disk artifacts**. This is the heart of the architecture.
+
+```
+┌─────────────┐  writes    ┌──────────────────┐  reads  ┌──────────────┐
+│  @product   ├───────────▶│  spec.md         │◀────────┤  @architect  │
+└─────────────┘            │  prd.md          │         └──────────────┘
+                           └──────────────────┘
+                                    │
+                                    ▼ reads
+                           ┌──────────────────┐  reads  ┌──────────────┐
+                           │  @architect      │         │  @dev        │
+                           │  writes →        ├────────▶│              │
+                           │  architecture.md │         └──────┬───────┘
+                           └──────────────────┘                │
+                                                               ▼ writes
+                                                      ┌──────────────────┐
+                                                      │  dev-state.md    │
+                                                      │  (code)          │
+                                                      └────────┬─────────┘
+                                                               │ reads
+                                                               ▼
+                                                      ┌──────────────┐
+                                                      │  @qa         │
+                                                      └──────────────┘
+```
+
+**Advantage:** if a session drops, the next agent only needs to read the artifacts. No conversational memory is lost.
+
+---
+
+## Where artifacts live
+
+```
+your-project/
+└── .aioson/
+    └── context/
+        ├── project.context.md      ← global context (created by @setup)
+        ├── project-pulse.md        ← live state, updated each session
+        ├── architecture.md         ← decisions from @analyst and @architect
+        ├── prd.md                  ← output of @product
+        ├── design-doc.md           ← output of @ux-ui
+        ├── tasks.md                ← output of @pm
+        ├── dev-state.md            ← output of @dev (current status)
+        ├── test-plan.md            ← output of @qa
+        ├── security-findings-*.json ← output of @pentester
+        ├── handoff-protocol.json   ← last handoff between agents
+        ├── features/<slug>/        ← features in development
+        ├── done/                   ← archived features (after feature:close)
+        └── dossier/<slug>/         ← feature dossier (Phase 1+ of continuity)
+```
+
+---
+
+## "I don't know which agent to use"
+
+Use `@neo`. It's literally the "I'm lost" agent.
+
+```
+You in Claude Code:
+> @neo
+
+@neo:
+> Reading project-pulse.md... you're on the "my-store" project, SMALL classification,
+  with the "checkout-stripe" feature in progress. @dev finished yesterday.
+> Natural next step: @qa to write tests for the feature.
+> If you want a security review before QA: @pentester.
+> If you want to pair first: @deyvin.
+```
+
+---
+
+## Real dialogue — full SMALL cycle
+
+```
+─── Session 1 ───
+You > @setup
+@setup > Detected Node.js + Express + Postgres. Project type? [api/web_app/site/...]
+You > web_app
+@setup > How many user types? How many external integrations?
+You > 2 / 3
+@setup > Classified as SMALL. Interaction language? [en/pt-BR/es/fr]
+You > en
+@setup > project.context.md created. Next: @product.
+
+─── Session 1 (continued) ───
+You > @product
+@product > Let's start a feature. What's it called? What's the problem?
+You > "checkout-stripe", complete order with card payment.
+@product > [...several questions...] Spec created at context/features/checkout-stripe/spec.md.
+@product > Next: @analyst to map the domain.
+
+─── Session 2 (next day) ───
+You > @neo
+@neo > You stopped at @product. Next: @analyst.
+You > @analyst
+@analyst > [reads spec.md, examines codebase] Mapped: Order, Customer, Payment, OrderItem.
+@analyst > Decision recorded in architecture.md. Next: @architect.
+
+─── and so on until @qa ───
+```
+
+---
+
+## Next step
+
+- Ready to try it? → [First project from scratch](../2-start/first-project.md)
+- Confused about a term? → [Glossary](./glossary.md)
+- Curious about why all this? → [Why it exists](./why-it-exists.md)

package/docs/en/1-understand/glossary.md

@@ -0,0 +1,288 @@
+# AIOSON Glossary
+
+> **Who this is for:** anyone reading the other docs and tripping over jargon.
+> **Reading time:** reference — read what you need.
+> **How to use:** Ctrl+F is your friend.
+
+Terms in alphabetical order. Each entry has a **short definition** + **concrete example** + **where to learn more**.
+
+---
+
+## Agent
+
+**Definition:** a virtual specialist with its own prompt, its own rules, and a specific responsibility. Lives in `.aioson/agents/<name>.md`.
+
+**Example:** `@dev` is the agent that implements code. `@qa` is the one that writes tests. `@pentester` is the one that tries to break the feature on purpose.
+
+**How to invoke:** type `@name` in your AI client (Claude, Codex, Gemini, OpenCode) or describe the intent in natural language ("let's implement the feature").
+
+---
+
+## AIOSON
+
+**Definition:** the framework itself. An npm package (`@jaimevalasek/aioson`) that installs a structure of agents, rules, and tools in your project.
+
+**Example:** running `npx @jaimevalasek/aioson init my-app` creates the `.aioson/` folder in your project.
+
+---
+
+## AIOSON Cloud / aioson.com
+
+**Definition:** the hosted service for publishing and installing squads, genomes, and skills across projects.
+
+**Example:** you create a squad of agents for the legal domain in your project, run `aioson system:publish`, and any other project can run `aioson system:install <slug>`.
+
+**Where to learn more:** `5-reference/aioson-com-store.md`.
+
+---
+
+## Artifact
+
+**Definition:** any file that an agent creates or updates as output of its work.
+
+**Examples:**
+- `.aioson/context/project.context.md` — project context (created by `@setup`)
+- `.aioson/context/features/<slug>/spec.md` — feature spec (created by `@product`/`@analyst`)
+- `.aioson/context/dossier/<slug>/` — feature dossier (created by the agent chain)
+
+**Why it matters:** Article III of the Constitution says important work leaves an artifact. Without an artifact, the work "didn't happen" officially.
+
+---
+
+## Brains
+
+**Definition:** procedural memory of an agent — structured knowledge in "nodes" (Zettelkasten style) that the agent loads on demand.
+
+**Example:** `@site-forge` has brains with 14 nodes about how `pt.squarespace.com` structures its pages, used when you ask for a clone.
+
+**Where it lives:** `.aioson/brains/<agent>/`.
+
+---
+
+## Briefing
+
+**Definition:** a pre-PRD document that frames a problem before it becomes a feature. Output of the `@briefing` agent.
+
+**Example:** you have 5 scattered notes about an idea. `@briefing` transforms them into a structured briefing with problem, hypotheses, and discovery frames.
+
+---
+
+## Classification (MICRO / SMALL / MEDIUM)
+
+**Definition:** the size of the project, calculated from 3 factors (user types, external integrations, business rules). Determines how much ceremony the workflow applies.
+
+**How it works:**
+- 0–1 points → **MICRO** (`@setup → @product → @dev`)
+- 2–3 points → **SMALL** (`@setup → @product → @analyst → @architect → @dev → @qa`)
+- 4–6 points → **MEDIUM** (full workflow, all gates, all artifacts)
+
+**Where it appears:** `classification:` in the `project.context.md` frontmatter.
+
+---
+
+## AI Client
+
+**Definition:** the program where you actually talk to the AI. AIOSON is client-agnostic — it works with several.
+
+**Officially supported:** Claude Code, Codex CLI, Gemini CLI, OpenCode.
+**Also works via terminal:** VS Code, Cursor, Windsurf, JetBrains IDEs, Zed, Antigravity (any that opens a terminal).
+
+**Where to learn more:** `5-reference/clientes-ai.md`.
+
+---
+
+## Committer
+
+**Definition:** the `@committer` agent that generates professional commit messages from the diff and context.
+
+**Example:** after implementing a feature, `@committer` reads what changed, proposes the message, shows a checkbox in the terminal, and commits.
+
+---
+
+## Constitution
+
+**Definition:** the 6 (currently 7, with Zero Trust) principles in `.aioson/constitution.md`. No agent can contradict an article.
+
+**Full detail:** [Why it exists](./why-it-exists.md#the-6-principles-of-the-constitution).
+
+---
+
+## Context Pack
+
+**Definition:** a minimal, curated set of files that an agent reads to do its work — instead of scanning the entire project.
+
+**Why it matters:** saves context window. `@dev` for a "add a form field" feature doesn't need to read the whole project.
+
+---
+
+## Continuity (agent-chain-continuity)
+
+**Definition:** the system that ensures if a session drops in the middle of a feature, the next session can resume without losing context. Implemented in phases (1 to 8) across Mar–May 2026.
+
+**Main components:** `dossier`, `dev-state.md`, `dev-resume`, `handoff-protocol.json` v2, drift detection.
+
+---
+
+## Design Skill
+
+**Definition:** a skill specialized in a visual system (colors, typography, spacing, components). Can be a native skill or a hybrid created by `@design-hybrid-forge`.
+
+**Ready-made examples:** Clean SaaS UI, Aurora Command UI, Cognitive Core UI, Bold Editorial UI, Warm Craft UI, Glassmorphism UI, Neo Brutalist UI.
+
+**Where to choose:** during `aioson init`, in the wizard.
+
+---
+
+## Dossier (Feature Dossier)
+
+**Definition:** a folder `.aioson/context/dossier/<slug>/` that contains **everything** about a feature in progress: spec, plan, decisions, touched code, research index, status.
+
+**Why it matters:** it's the single point any agent entering the feature consults. Replaces "I'll re-read the entire history."
+
+**Commands:** `aioson dossier:init`, `dossier:show`, `dossier:add-research`, `dossier:audit`.
+
+---
+
+## Genome
+
+**Definition:** "cognitive DNA" of a persona — a structured YAML with personality traits (DISC, Enneagram, Big Five, MBTI, HEXACO-H), style, tone, and advisor instructions.
+
+**What it's for:** creating advisors (personalized assistants) that reason like a specific person. Example: generate a "Steve Jobs style" advisor to review pitch decks.
+
+**Current version:** Genome 4.0 with `anchor_prompt`, `relations`, `hexaco_h`, `trait_interactions`.
+
+**Where to learn more:** `5-reference/genome-4.0-spec.md` (in progress).
+
+---
+
+## Handoff
+
+**Definition:** the moment when an agent finishes its part and passes to the next, leaving the artifacts ready.
+
+**Where it's recorded:** `.aioson/context/handoff-protocol.json` (v2).
+
+---
+
+## Live Session
+
+**Definition:** a "tracked" session — an envelope that records each milestone in the local SQLite for the dashboard to display.
+
+**Commands:** `aioson live:start`, `live:status`, `live:handoff`, `live:close`.
+
+---
+
+## Memory
+
+**Definition:** AIOSON's persistent memory. Recently gained an **active retrieval** layer — agents can search for relevant memories, not just read everything.
+
+**Where it lives:** `.aioson/memory/` (in the project) and `~/.claude/projects/<hash>/memory/` (per user, for Claude Code).
+
+---
+
+## Neo
+
+**Definition:** the `@neo` agent — intelligent router. It looks at the project state and tells you which agent makes sense to invoke now.
+
+**When to use:** when you don't know how to continue ("show project status", "where do I start?"). Recently gained a full ecosystem catalog and *ecosystem-inquiry* mode.
+
+---
+
+## Pentester
+
+**Definition:** `@pentester` agent that does adversarial security review — scans OWASP Top 10, LLM Top 10, supply chain, and maps attack surfaces.
+
+**When to use:** before publishing a feature to production, or when you need a specific audit point.
+
+---
+
+## Pipeline / Workflow
+
+**Definition:** the ordered sequence of agents that AIOSON applies to a feature, based on the classification.
+
+**Central command:** `aioson workflow:next .` — shows which agent is next.
+
+---
+
+## Plan
+
+**Definition:** documents in `/plans/` (project root) that describe a planned execution. Not committed (local memory).
+
+**What they're for:** planning before executing; serve as "seed plans" for features.
+
+---
+
+## Profiler (researcher / enricher / forge)
+
+**Definition:** the 3-stage pipeline that creates a Genome from a public figure.
+
+1. `@profiler-researcher` — collects raw material.
+2. `@profiler-enricher` — analyzes cognitively.
+3. `@profiler-forge` — generates the Genome 4.0 and the advisor.
+
+---
+
+## Project Pulse
+
+**Definition:** the file `.aioson/context/project-pulse.md` — the live global state of the project. Read at the start of each session, updated at the end.
+
+**What it's for:** give any incoming agent a snapshot of "what's happening in this project right now."
+
+---
+
+## Rules
+
+**Definition:** *hard* project rules, in `.aioson/rules/*.md`. Unlike loose instructions in a prompt, rules are read automatically by all applicable agents.
+
+**Example:** `security-baseline.md` declares the `SEC-SBD-01..08` controls that `@dev` and `@qa` consume.
+
+---
+
+## Skill
+
+**Definition:** a pluggable instruction package. Types:
+- **Process skills** — methodologies (e.g., `aioson-spec-driven`)
+- **Design skills** — visual systems (e.g., `clean-saas-ui`)
+- **Static skills** — fixed domain knowledge
+- **Dynamic skills** — generate instructions at runtime
+
+**Where they live:** `.aioson/skills/` in the project, or globally.
+
+---
+
+## Squad
+
+**Definition:** a group of custom agents — tailor-made for a domain the standard team doesn't cover well.
+
+**Example:** a "legal compliance" squad with agents `@regulator`, `@attorney`, `@auditor`, under the command of `@squad`.
+
+**Commands:** `aioson squad:assemble`, `squad:agent-create`, `squad:refresh`.
+
+---
+
+## Tester
+
+**Definition:** `@tester` agent — systematic test engineering for already-implemented apps. Use when regular `@qa` isn't enough (legacy, brownfield, gaps across 3+ modules).
+
+**Recent:** gained *coverage quality tier* and *test smell audit*.
+
+---
+
+## Validator
+
+**Definition:** `@validator` agent — technically validates a feature against the success contract defined in the spec, before close-out.
+
+---
+
+## Workflow
+
+See **Pipeline / Workflow**.
+
+---
+
+## Zero Trust
+
+**Definition:** Article VII of the Constitution. Security is not an "optional feature" — it's the default state. Every feature goes through automatic baseline checks.
+
+---
+
+Term not found? Search the [Ecosystem map](./ecosystem-map.md) or the [agents guide](../README.md).

package/docs/en/1-understand/what-is-aioson.md

@@ -0,0 +1,94 @@
+# What is AIOSON
+
+> **Who this is for:** anyone who hasn't used it yet.
+> **Reading time:** 5 min
+> **What you'll know after:** what AIOSON is, what it does for you, and when *not* to use it.
+
+---
+
+## In one sentence
+
+AIOSON turns a single generic AI into **a team of specialists that take turns** throughout your project — each focused on one stage, with clear rules about when to start and when to hand off to the next one.
+
+## The building crew analogy
+
+Imagine you want to build a house.
+
+**Without AIOSON:** you hire one super-generic contractor and say "build my house." They try to be architect, bricklayer, electrician, plumber, and site inspector all at once. Sometimes it works. Often they forget details. When something goes wrong, they don't remember why they made a decision two hours ago.
+
+**With AIOSON:** you have a team.
+
+- **Briefing** listens to your raw idea (the "napkin sketch") and hands back a structured briefing — with risks and open questions — *before* it becomes a project.
+- **Product** understands what you want to build and why — and writes the PRD.
+- **Sheldon** reviews the PRD like a senior architect who has seen everything: points out gaps, researches what's outdated, reads your actual code, and decides whether to enrich the PRD or create a phased plan. Can review multiple times.
+- **Analyst** discovers what already exists in the codebase and what's missing.
+- **Architect** designs the structure.
+- **UX-UI** designs how the end user will live there.
+- **Dev** builds.
+- **Deyvin** is the site foreman who picks up the job when you return from a trip: reads what's confirmed, flags what's inferred, and proceeds one small step at a time without you having to re-explain anything.
+- **QA** inspects.
+- **Pentester** tests the locks (security).
+- **Committer** writes the meeting minutes (commit message).
+
+Each one knows when to step in, when to step out, and what document to hand to the next. You talk to any of them by typing `@name` in your AI client.
+
+## What this changes in practice
+
+| Without AIOSON | With AIOSON |
+|---|---|
+| One massive prompt trying to do everything | Several smaller prompts, each with clear scope |
+| The AI "forgets" earlier decisions mid-work | Decisions become **disk artifacts** (specs, dossiers, plans) |
+| You start from scratch when you switch sessions | The next session reads the artifacts and picks up where it left off |
+| Hard to go back and audit what was done | Every agent leaves a trail: what it decided, why, based on what |
+| Large teams disagree on each AI's style | Everyone uses the same set of agents and rules |
+
+## What AIOSON installs in your project
+
+When you run `aioson init`, it creates:
+
+```
+your-project/
+├── .aioson/
+│   ├── agents/              ← prompts for each specialist
+│   ├── config.md            ← project rules (size, language, stack)
+│   ├── constitution.md      ← the 6 principles no one overrides
+│   ├── context/             ← live context: project.context.md, project-pulse.md
+│   ├── rules/               ← hard rules agents follow (security, etc.)
+│   ├── skills/              ← pluggable packages (design systems, processes)
+│   └── runtime/             ← local telemetry (SQLite)
+├── .claude/  .codex/  .gemini/  .windsurf/   ← integration with each AI client
+├── CLAUDE.md  AGENTS.md  OPENCODE.md         ← per-client instructions
+└── docs/                                      ← optional documentation
+```
+
+Open your favorite AI client and type `@setup`, `@product`, `@dev`, etc. — the agents take over.
+
+## Works with any AI client
+
+Works with **any IDE that has a terminal**:
+
+- Claude Code · Codex CLI · Gemini CLI · OpenCode
+- VS Code, Google Antigravity, Cursor, Windsurf, JetBrains, Zed (with any of the clients above)
+
+Agents are *prompts*, not plugins. They live in `.md` files and your AI client reads them when you invoke via `@name`.
+
+## When AIOSON shines
+
+- **Projects where decisions matter** — you want traceability, not improvisation.
+- **Teams** — multiple humans and multiple AIs need to read the same narrative.
+- **Long or resumed sessions** — you need to stop today and come back tomorrow without losing context.
+- **When you want specialization** — serious security, careful UX, systematic testing.
+
+## When *not* to use AIOSON
+
+- **A 20-line script** that runs once. Use a direct prompt, no ceremony.
+- **You want to explore an idea freely** in 5 minutes. AIOSON asks for setup first.
+- **You won't open the project again.** The value is precisely in repeated sessions.
+
+For these cases, AIOSON itself has a lightweight path — the **MICRO** classification (`@setup → @product → @dev`). But if even that doesn't fit, don't force it.
+
+## Next step
+
+- Want to understand *why* AIOSON was designed this way? → [Why it exists](./why-it-exists.md)
+- Want to see the full team at a glance? → [Ecosystem map](./ecosystem-map.md)
+- Want to start now? → [First project from scratch](../2-start/first-project.md)