diff --git a/CHANGELOG.md b/CHANGELOG.md index 770d6aa..89b6df7 100644 --- a/CHANGELOG.md +++ b/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)). diff --git a/README.md b/README.md index 9c4a7e9..94450ae 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ 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/) --- @@ -122,7 +122,7 @@ CLI: `aura agent create`, `aura run`, `aura export`, `aura report show`, `aura c | 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) | diff --git a/aura/cli/help_text.py b/aura/cli/help_text.py index 8d5bcea..8d14a4c 100644 --- a/aura/cli/help_text.py +++ b/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 ", "JSON profile by name, agent_ref, or aura_id"), ("aura agent set …", "update ref, purpose, skills, variables, rules"), ], - _DOCS_CLI, + _DOCS_ONBOARDING, ), ( "Sessions", @@ -43,7 +44,7 @@ ("aura --home ", "override AURA_HOME for this invocation"), ("aura --project ", "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, ), ] diff --git a/aura/cli/help_ui.py b/aura/cli/help_ui.py index 09fc6b8..ddb9343 100644 --- a/aura/cli/help_ui.py +++ b/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}")) diff --git a/docs/INDEX.md b/docs/INDEX.md index 87467e6..c19706c 100644 --- a/docs/INDEX.md +++ b/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 | diff --git a/docs/concepts.md b/docs/concepts.md index d13c08c..dd7d68a 100644 --- a/docs/concepts.md +++ b/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) diff --git a/docs/getting-started.md b/docs/getting-started.md index cb6c8f3..d8e9827 100644 --- a/docs/getting-started.md +++ b/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 diff --git a/docs/onboarding.md b/docs/onboarding.md new file mode 100644 index 0000000..60a13c9 --- /dev/null +++ b/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 diff --git a/docs/using-aura.md b/docs/using-aura.md index ea29f67..eec386b 100644 --- a/docs/using-aura.md +++ b/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 diff --git a/examples/README.md b/examples/README.md index 7f8d1c7..f841a30 100644 --- a/examples/README.md +++ b/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/`. diff --git a/tests/test_cli.py b/tests/test_cli.py index c196882..563fe3d 100644 --- a/tests/test_cli.py +++ b/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):