docs: add onboarding guide for first-run setup flow (#13)

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Onboarding guide** — [docs/onboarding.md](docs/onboarding.md) step-by-step flow: posture, identity, body wiring, receipt review ([#13](https://github.com/ARPAHLS/aura/issues/13)).
 - **`aura report show`** — print a human-readable audit report, or use `--json` for CI output ([#25](https://github.com/ARPAHLS/aura/issues/25)).
 - **Session close and export guide** — `using-aura.md` now covers audit reports, export commands, and receipt review ([#37](https://github.com/ARPAHLS/aura/issues/37)).
 - **Break observer preset** — `observer.alert` on repeated tool intents ([#34](https://github.com/ARPAHLS/aura/issues/34)).

README.md

@@ -114,15 +114,15 @@ print(run.exports)
 
 CLI: `aura agent create`, `aura run`, `aura export`, `aura report show`, `aura compare`, `aura export-otel`, `aura verify chain`.
 
-→ [getting-started.md](docs/getting-started.md) · [examples/](examples/)
+→ [getting-started.md](docs/getting-started.md) · [onboarding.md](docs/onboarding.md) · [examples/](examples/)
 
 ---
 
 ## Documentation
 
 | Topic | Links |
 | :--- | :--- |
-| **Start** | [getting-started.md](docs/getting-started.md) · [concepts.md](docs/concepts.md) · [using-aura.md](docs/using-aura.md) |
+| **Start** | [onboarding.md](docs/onboarding.md) · [getting-started.md](docs/getting-started.md) · [concepts.md](docs/concepts.md) · [using-aura.md](docs/using-aura.md) |
 | **Integration** | [reference-tool-host-capstone.md](docs/guides/reference-tool-host-capstone.md) · [guides/aura-on-skillware.md](docs/guides/aura-on-skillware.md) · [skillware-integration.md](docs/skillware-integration.md) · [sequencer.md](docs/sequencer.md) |
 | **Identity & audit** | [trust-paths.md](docs/trust-paths.md) · [outputs.md](docs/outputs.md) |
 | **Compare & position** | [comparison.md](docs/comparison.md) · [ROADMAP.md](docs/ROADMAP.md) |

aura/cli/help_text.py

@@ -4,6 +4,7 @@
 
 from typing import List, Tuple, Union
 
+_DOCS_ONBOARDING = "https://github.com/ARPAHLS/aura/blob/main/docs/onboarding.md"
 _DOCS_CLI = "https://github.com/ARPAHLS/aura/blob/main/docs/using-aura.md"
 _DOCS_GETTING_STARTED = "https://github.com/ARPAHLS/aura/blob/main/docs/getting-started.md"
 _DOCS_TESTING = "https://github.com/ARPAHLS/aura/blob/main/docs/TESTING.md"
@@ -17,7 +18,7 @@
             ("aura agent show <id>", "JSON profile by name, agent_ref, or aura_id"),
             ("aura agent set <id> …", "update ref, purpose, skills, variables, rules"),
         ],
-        _DOCS_CLI,
+        _DOCS_ONBOARDING,
     ),
     (
         "Sessions",
@@ -43,7 +44,7 @@
             ("aura --home <dir>", "override AURA_HOME for this invocation"),
             ("aura --project <dir>", "one-shot project-scoped .aura/ storage"),
         ],
-        _DOCS_GETTING_STARTED,
+        _DOCS_ONBOARDING,
     ),
     (
         "General",
@@ -52,7 +53,7 @@
             ("aura --help", "grouped command reference"),
             ("aura version", "installed package version"),
         ],
-        _DOCS_CLI,
+        _DOCS_ONBOARDING,
     ),
 ]
 

aura/cli/help_ui.py

@@ -12,6 +12,7 @@
     CLI_USAGE_EXAMPLES,
     HELP_GROUPS,
     _DOCS_CLI,
+    _DOCS_ONBOARDING,
     _HELP_MENU,
     _NAV_BACK,
     _NAV_EXIT,
@@ -88,6 +89,7 @@ def _print_help_static_topic(console: Console, topic: str) -> None:
         console.print('  pip install -e ".[dev]"  # local development', style="dim")
     elif topic == "docs":
         console.print(Text("Docs", style=f"bold {TABLE_STYLE}"))
+        console.print(f"  {_DOCS_ONBOARDING}", style=f"dim {SPLASH_STYLE}")
         console.print(f"  {_DOCS_CLI}", style=f"dim {SPLASH_STYLE}")
     elif topic == "interactive":
         console.print(Text("Interactive mode", style=f"bold {TABLE_STYLE}"))
@@ -108,6 +110,7 @@ def cmd_help(*, console: Console | None = None, brief: bool = True) -> None:
         console.print("  pip install aura-harness", style="dim")
         console.print()
         console.print(Text("Docs", style=f"bold {TABLE_STYLE}"))
+        console.print(f"  {_DOCS_ONBOARDING}", style=f"dim {SPLASH_STYLE}")
         console.print(f"  {_DOCS_CLI}", style=f"dim {SPLASH_STYLE}")
         console.print()
         console.print(Text("Interactive mode", style=f"bold {TABLE_STYLE}"))

docs/INDEX.md

@@ -6,6 +6,7 @@
 
 | Doc | Content |
 |---|---|
+| [onboarding.md](onboarding.md) | **Start here** — install → posture → agent → body → receipt |
 | [getting-started.md](getting-started.md) | Install, example, CLI |
 | [using-aura.md](using-aura.md) | Membrane, personas, SDK |
 | [contributing/ai_native_workflow.md](contributing/ai_native_workflow.md) | Agents and operators |

docs/concepts.md

@@ -74,4 +74,4 @@ How the body executes (Python script, Skillware host, future: LangGraph). AURA w
 
 Default: `~/.aura/` (override with `AURA_HOME`). Project-local: set `storage: project` in `aura.project.yaml` → `.aura/` in project root.
 
-→ [using-aura.md](using-aura.md) · [glossary.md](glossary.md)
+→ [onboarding.md](onboarding.md) — storage, identity, and first run · [glossary.md](glossary.md)

docs/getting-started.md

@@ -1,5 +1,7 @@
 # Getting started
 
+New to AURA? Follow [onboarding.md](onboarding.md) for the full setup flow (posture → agent → body → receipt).
+
 ## Install
 
 ```bash
@@ -116,11 +118,12 @@ ids:
 
 ## Examples
 
-See [examples/](../examples/README.md) — including [sequencer_pipeline.py](../examples/sequencer_pipeline.py), [07-observer-presets](../examples/07-observer-presets/), and the ToolHost capstone checklist in [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md).
+See [examples/](../examples/README.md) — including [sequencer_pipeline.py](../examples/sequencer_pipeline.py), [07-observer-presets](../examples/07-observer-presets/), and the ToolHost capstone in [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md). Order: [onboarding.md](onboarding.md#examples-learning-path).
 
 ## Next
 
-- [using-aura.md](using-aura.md) — membrane, personas, observers
+- [onboarding.md](onboarding.md) — step-by-step first run
+- [using-aura.md](using-aura.md) — membrane, postures, observers
 - [skillware-integration.md](skillware-integration.md) — Skillware host
 - [concepts.md](concepts.md) — agent, session, sequencer
 - [comparison.md](comparison.md) — vs orchestrators and eval harnesses

docs/onboarding.md

@@ -0,0 +1,204 @@
+# Onboarding — use AURA correctly
+
+Step-by-step path from install to a reviewable session receipt. For membrane detail see [using-aura.md](using-aura.md); for terms see [concepts.md](concepts.md).
+
+---
+
+## 1. Install and storage
+
+```bash
+git clone https://github.com/ARPAHLS/aura.git
+cd aura
+python -m venv .venv
+# Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Confirm the CLI and resolved paths:
+
+```bash
+aura version
+aura config show
+aura paths
+```
+
+| Path | Default | Override |
+|---|---|---|
+| Agent profiles | `{AURA_HOME}/agents/` | `AURA_HOME` env or `aura --home` |
+| Session exports | `{AURA_HOME}/sessions/` | same |
+| Project storage | global `~/.aura/` | `aura paths set-storage project` + `aura.project.yaml` |
+
+Use a dedicated home for experiments: `AURA_HOME=/tmp/aura-demo aura paths`.
+
+---
+
+## 2. Choose a posture
+
+AURA is the **coat** around your loop — not the loop itself.
+
+| Posture | You want | Typical wiring |
+|---|---|---|
+| **Audit** | Record what happened; rules optional | `agent().session()`, `emit()`, export on close |
+| **Prescriptive** | Declared steps, gates, conformance on close | Sequencer spec + tool host + rules + CI receipt check |
+
+→ [using-aura.md — Choose a posture](using-aura.md#choose-a-posture)
+
+Stack-specific bodies (Ollama, OpenAI, Skillware registry) live under [integrations/](integrations/README.md). Core patterns live under [examples/](../examples/README.md).
+
+---
+
+## 3. Identity and constitution
+
+Create an agent with stable audit anchors:
+
+```bash
+aura agent create research-bot \
+  --ref acme/research-bot \
+  --purpose "Research and draft outreach"
+```
+
+| Field | Role |
+|---|---|
+| **`agent_ref`** | Human/CI anchor (`tenant/slug`) |
+| **`aura_id`** | Internal ULID (auto unless you set `--aura-id`) |
+| **`policy_version`** | Tie runs to a policy snapshot (profile or per-session) |
+| **`purpose`** | Declared intent — appears in profile and spine |
+| **`rules`** | Constitution — `confirm_before`, `allow_tools`, `deny_tools`, token limits |
+| **`ids`** | Your external IDs (company, vendor assistant id) — AURA does not replace them |
+
+Update later: `aura agent set research-bot --ref acme/research-bot --variable model=gpt-4o-mini`.
+
+→ [trust-paths.md](trust-paths.md) · [concepts.md — Agent](concepts.md#agent)
+
+---
+
+## 4. Wire the body
+
+Pick how your loop executes inside the session:
+
+| Body style | When | Entry |
+|---|---|---|
+| **Emit-only** | Custom script; you emit spine events yourself | [examples/08-emit-only-loop](../examples/08-emit-only-loop/) |
+| **Tool host** | Skills/tools at egress; membrane enforces rules | `SkillwareHost` or any `ToolHost` — [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md) |
+| **Sequencer** | Declared step order + gates | [sequencer_pipeline.py](../examples/sequencer_pipeline.py) |
+| **Stack integration** | Ollama / cloud API as body | [integrations/README.md](integrations/README.md) |
+
+Minimal SDK pattern (audit posture):
+
+```python
+from aura import agent, configure
+
+configure()
+ag = agent("research-bot")
+
+with ag.session(mode="script") as run:
+    run.emit("turn.start", {"input": "hello"})
+    run.emit("turn.end", {"output": "done", "tokens": 42})
+
+print(run.session_id, run.exports)
+```
+
+---
+
+## 5. Run, approve gates, record principal
+
+Run a script under an agent profile:
+
+```bash
+aura run research-bot path/to/script.py
+```
+
+When a rule requires confirmation, satisfy it in code and **record the approver**:
+
+```python
+run.approve(request_id, principal="operator@corp")
+```
+
+The principal appears in the audit trail, summary, and OTel export as `aura.principal`.
+
+CLI after close:
+
+```bash
+aura logs aura_sess_xxxxxxxxxxxx
+aura report show aura_sess_xxxxxxxxxxxx
+aura report show aura_sess_xxxxxxxxxxxx --json
+```
+
+→ [using-aura.md — Session close and export](using-aura.md#session-close-and-export)
+
+---
+
+## 6. Review the receipt
+
+On session close (default), AURA writes:
+
+| Artifact | Use |
+|---|---|
+| `{session_id}.jsonl` | Hash-chained event trail |
+| `{session_id}.summary.json` | Conformance + `AuditReport` |
+| `{session_id}.otel.jsonl` | Span-style export (on close; refresh with `export-otel`) |
+
+```bash
+aura export aura_sess_xxxxxxxxxxxx
+aura export-otel aura_sess_xxxxxxxxxxxx
+aura verify chain ~/.aura/sessions/aura_sess_xxxxxxxxxxxx.jsonl
+aura compare sess_a sess_b
+```
+
+Inspect verdict (`pass` / `warn` / `fail`), findings, and `hash_chain_valid` before treating a run as complete. A conformance pass can still `warn` when the report finds advisory issues.
+
+→ [outputs.md](outputs.md)
+
+---
+
+## 7. CI hook (sketch)
+
+Fail the job when the hash chain or report verdict is unacceptable:
+
+```bash
+pytest --ignore=tests/integration
+aura verify chain "$SESSION_JSONL" || exit 1
+aura report show "$SESSION_ID" --json | jq -e '.audit_report.verdict != "fail"'
+```
+
+Use project-scoped storage in CI: `AURA_HOME=$RUNNER_TEMP/aura`.
+
+→ [TESTING.md](TESTING.md)
+
+---
+
+## Examples learning path
+
+Run in order from repo root after `pip install -e .`:
+
+| Step | Example | Teaches |
+|---|---|---|
+| 1 | [minimal_loop.py](../examples/minimal_loop.py) | Audit posture — emit + export |
+| 2 | [guarded_tools.py](../examples/guarded_tools.py) | Rules, approval gates, allow/deny |
+| 3 | [task_mode.py](../examples/task_mode.py) | Task mode + `complete_goal()` |
+| 4 | [sequencer_pipeline.py](../examples/sequencer_pipeline.py) | Prescriptive pipeline + mock host |
+| 5 | [05-skillware-skill-types](../examples/05-skillware-skill-types/) | ToolHost + three skill categories |
+| 6 | [06-skillware-sequencer-chain](../examples/06-skillware-sequencer-chain/) | Declarative chain + conditional `when` |
+| 7 | [07-observer-presets](../examples/07-observer-presets/) | Monitor + Break observer presets |
+| 8 | [08-emit-only-loop](../examples/08-emit-only-loop/) | Loose coat — no tool host |
+
+Capstone checklist: [reference-tool-host-capstone.md](guides/reference-tool-host-capstone.md).
+
+---
+
+## Deferred (roadmap)
+
+Not required for first successful run:
+
+- **Goals and schedules** — tracked in [GH #46](https://github.com/ARPAHLS/aura/issues/46)
+- **Run auth / gatekeeper coat** — [GH #50](https://github.com/ARPAHLS/aura/issues/50)
+- **Integrations index polish** — [GH #19](https://github.com/ARPAHLS/aura/issues/19) / [GH #20](https://github.com/ARPAHLS/aura/issues/20)
+
+---
+
+## Next
+
+- [getting-started.md](getting-started.md) — install snippets
+- [using-aura.md](using-aura.md) — SDK, CLI, membrane
+- [integrations/README.md](integrations/README.md) — pick your stack
+- [INDEX.md](INDEX.md) — full doc map

docs/using-aura.md

@@ -2,6 +2,8 @@
 
 How to attach AURA to your agent loop — from lightweight audit logging to prescriptive pipelines.
 
+→ New here? [onboarding.md](onboarding.md) walks install through session receipt.
+
 ---
 
 ## Choose a posture

examples/README.md

@@ -36,6 +36,8 @@ Live registry skills (examples 05–06): `$env:SKILLWARE_LIVE="1"` (PowerShell).
 
 → Capstone checklist: [docs/guides/reference-tool-host-capstone.md](../docs/guides/reference-tool-host-capstone.md)
 
+**Learning order:** [onboarding.md](../docs/onboarding.md#examples-learning-path) — run examples 1→8 in sequence.
+
 ## Script excerpts
 
 Each script uses a top module docstring, then section comments for setup, session, emit, and close / expected export. Core examples stay as flat scripts here; stack-specific demos belong under `docs/integrations/`.

tests/test_cli.py

@@ -144,6 +144,14 @@ def test_cli_help_grouped(run_aura):
     assert "aura agent list" in result.stdout
     assert "aura verify chain path/to/session.jsonl" in result.stdout
     assert "interactive" in result.stdout.lower()
+    assert "onboarding.md" in result.stdout
+
+
+def test_cli_help_groups_link_onboarding():
+    from aura.cli.help_text import HELP_GROUPS, _DOCS_ONBOARDING
+
+    doc_links = {group[2] for group in HELP_GROUPS}
+    assert _DOCS_ONBOARDING in doc_links
 
 
 def test_cli_interactive_splash_and_exit(run_aura):