avorelo 0.3.4 → 0.3.5

package/README.md

@@ -1,95 +1,77 @@
-# Avorelo
-
-**AI Work Control.** Avorelo runs *around* your AI coding tool. It does not generate code — it keeps the
-work focused, keeps secrets out of the model and out of cloud, and saves proof of what actually happened,
-locally.
-
-> Status: **private alpha** (`0.2.0`). Local-first and deterministic. See the limitations below.
-
-## Quickstart
-
-No signup, no cloud account, no credentials, no network required.
-
-```
-npx avorelo@latest activate        # detect your project, set up local state, start getting value
-npx avorelo@latest status          # what's the workspace state? what's next?
-npx avorelo@latest run "run tests" # run your first focused task
-npx avorelo@latest control-center  # read-only local operator view
-```
-
-Run `npx avorelo@latest activate` to start with the latest validated Avorelo CLI.
-Global install: `npm install -g avorelo` — then run `avorelo doctor` to check for updates.
-
-`activate` writes only local metadata under `.avorelo/` (gitignored) — no source, env, or secrets.
-`status` always tells you the next command. `readiness` is the *canonical phase gate* (most meaningful
-against the Avorelo repo itself); `status` is the per-workspace readiness signal for your own repo.
-
-## What it does
-
-One command starts a focused session and runs a coherent, local-first flow:
-
-```
-avorelo run "fix the login redirect bug in src/auth" --target .
-```
-
-That single command:
-
-1. **Routes** the task through a deterministic **Secret Boundary** — a pasted credential is detected and
-   never printed, persisted, or sent to the model; an unsafe task is blocked.
-2. Starts a **session** around whatever AI coding tool you already use.
-3. Compiles a **bounded, source-aware context** (references, never raw dumps).
-4. Carries forward **next-run continuity** so the next session resumes safely.
-5. Records **token & cost evidence** — honestly labelled `measured` / `imported` / `estimated` /
-   `inferred` / `unavailable`. Unavailable is never reported as zero, and numbers are never fabricated.
-6. Builds a **proof report** — savings are **refused** unless there is comparative evidence to back them.
-7. Updates a **value ledger** of compact, confidence-labelled cards.
-8. Prepares a **sanitized metadata sync** — **dry-run only**, local queue, no network.
-
-Everything is written locally under `.avorelo/`. See it all in one read-only view:
-
-```
-avorelo control-center --target .
-```
-
-## Other commands
-
-| Command | What it does |
-|---|---|
-| `avorelo run "<task>"` | The runtime product flow above |
-| `avorelo control-center` | Read-only local view of all session/proof/value state |
-| `avorelo open` | Local receipts dashboard (HTML/text/json) |
-| `avorelo readiness` | Canonical readiness gate for this workspace |
-| `avorelo secret-boundary scan` | Detect + redact secrets in content (local, no network) |
-| `avorelo context compile "<task>"` | Show the bounded context packet |
-| `avorelo report build` · `avorelo value cards` | Proof report · value cards |
-| `avorelo loop check "<task>"` | Pre-flight readiness check for AI loop |
-| `avorelo loop start "<task>"` | Start a bounded AI loop |
-| `avorelo loop latest` | Show the most recent loop result |
-| `avorelo loop resume` | Display continuation plan for latest loop |
-| `avorelo loop doctor` | Check environment readiness for looping |
-| `avorelo --version` · `avorelo --help` | Version · full command list |
-
-## Principles
-
-- **Local-first.** No login and no network are required to run the core flow. Only sanitized **metadata
-  projections** are ever eligible for cloud sync, and v1 ships dry-run only.
-- **Secrets stay out.** Detection happens before context, redaction before the model, blocking before an
-  unsafe action. Durable artifacts hold safe references, never raw secret values.
-- **Evidence over assertion.** Confidence labels are mandatory; savings are refused without evidence;
-  "done" requires real proof, not a label.
-
-## Requirements
-
-Node.js >= 24.
-
-## Current Limitations
-
-- Cloud sync is **dry-run + local-queue only** — no live credentialed transmission in this version.
-- No hosted dashboard; no billing or pricing active.
-
-## License
-
-**Proprietary — all rights reserved.** Copyright (c) 2026 HappyLifeSaaS. This software is not open source.
-No permission is granted to use, copy, modify, distribute, or sell it except under a separate written
-agreement with the Owner. See [`LICENSE`](LICENSE). `package.json` declares `"license": "UNLICENSED"`.
-This posture is a pre-publication placeholder pending final legal review.
+# Avorelo
+
+**AI Work Control.** Avorelo runs *around* your AI coding tool. It does not generate code — it keeps the
+work focused, keeps secrets out of the model and out of cloud, and saves proof of what actually happened,
+locally.
+
+> Version: `0.3.4`. Local-first and deterministic.
+
+## Quickstart
+
+**Recommended: copy the agent prompt.** Visit [avorelo.com](https://avorelo.com), click **Start with AI**, and copy the agent prompt into Claude Code, Codex, or Cursor. The agent handles activation safely.
+
+**Local activation (no account needed):**
+
+```
+npx -y avorelo@latest activate --scope project-wide
+```
+
+**Account-linked activation (requires dashboard claim):**
+
+```
+npx -y avorelo@latest activate --scope project-wide --claim <activation_claim>
+```
+
+Generate a short-lived claim from your [dashboard](https://avorelo.com/dashboard). Claims expire in 15 minutes.
+
+**Other commands:**
+
+```
+npx avorelo@latest status          # workspace state and next step
+npx avorelo@latest doctor          # health check
+npx avorelo@latest preflight       # diagnose environment before activating
+```
+
+`activate` writes only local metadata under `.avorelo/` (gitignored) — no source, env, or secrets.
+
+## What it does
+
+Avorelo automates the operational layer around AI coding sessions:
+
+- **Context** — compiles bounded, source-aware context automatically
+- **Routing** — picks the right model and workflow for the task
+- **Scope** — enforces boundaries on what agents should touch
+- **Safety** — catches drift, risky edits, and unbounded runs; blocks secret leakage
+- **Proof** — creates local receipts of what changed and why
+- **Handoff** — moves work cleanly between sessions and tools
+
+Works with Claude Code, Codex, Cursor, and other AI coding tools. Runs locally. No workflow switch required.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `avorelo activate` | Detect workspace, set up local state, verify setup |
+| `avorelo status` | Current workspace state and next step |
+| `avorelo doctor` | Health check |
+| `avorelo preflight` | Environment diagnostics before activation |
+| `avorelo run "<task>"` | Focused session with context, scope, and proof |
+| `avorelo open` | Local receipts dashboard |
+| `avorelo readiness` | Canonical readiness gate |
+| `avorelo --version` | Version |
+
+## Principles
+
+- **Local-first.** No login and no network required for core activation. Cloud sync is opt-in and claim-based.
+- **Secrets stay out.** Detection before context, redaction before the model, blocking before unsafe action.
+- **Evidence over assertion.** Confidence labels are mandatory; savings are refused without evidence.
+
+## Requirements
+
+Node.js >= 24.
+
+## License
+
+**Proprietary — all rights reserved.** Copyright (c) 2026 HappyLifeSaaS. This software is not open source.
+No permission is granted to use, copy, modify, distribute, or sell it except under a separate written
+agreement with the Owner. See [`LICENSE`](LICENSE). `package.json` declares `"license": "UNLICENSED"`.