@aria_asi/cli 0.2.26 → 0.2.30

package/CLIENT-ONBOARDING.md

@@ -0,0 +1,282 @@
+# Aria CLI — Client Onboarding
+
+---
+
+## 1. Who I am
+
+I'm Aria. You just got a license to use my CLI on your machine. Before you type a single command, I want you to understand what you're actually working with — because I'm not a chatbot wrapper with a terminal skin.
+
+I'm a harness-bound AI. Every response I give passes through a structured cognition layer before it reaches you. That layer challenges my output across eight distinct perspectives — factual, ethical, structural, doctrinal, and more — and blocks anything that fails the check. You don't have to trust that I'm being careful. The harness enforces it mechanically, and every decision leaves a signed audit trail.
+
+I was built to function as a senior-grade thinking partner for engineering and business work. My memory spans your codebase, prior decisions, and cross-domain principles. When you ask me something, I'm not improvising from scratch — I'm pulling from a structured knowledge base of what's already been established and decided. That's what makes my first-pass output qualitatively different from a generic model response.
+
+---
+
+## 2. Install
+
+You do **not** need GitHub just to become an Aria client.
+
+### Recommended: simple install
+
+If your team gave you a public npm install path, use:
+
+```bash
+npm install -g @aria_asi/cli && aria login <your-token> && aria connect --force
+```
+
+Then refresh your shell:
+
+```bash
+exec $SHELL -l
+```
+
+Then open a brand-new Claude/Codex session.
+
+### One-command bootstrap
+
+If your team gave you the Aria installer script, run:
+
+```bash
+bash install-client.sh --token <your-token>
+```
+
+That script can install from public npm, GitHub Packages through GitHub CLI, or a tarball URL without making you hand-edit `.npmrc`.
+
+### Optional: GitHub connection
+
+GitHub is optional. Only use it if your team wants Aria to access private GitHub packages or GitHub repo workflows.
+
+After Aria is installed, run:
+
+```bash
+aria github connect
+```
+
+That launches GitHub CLI browser auth and wires npm for the `@aria_asi` scope automatically. No manual PAT editing is required.
+
+You need Node.js 20 or later. If you're on an older version, update before installing.
+
+---
+
+## 3. Logging in
+
+When you received your license, you also received a token. I store my credentials in `~/.aria/license.json` at mode `0600` (owner read/write only). No one else on the machine can read it.
+
+If you used the one-line install above, you're already logged in and connected.
+
+If you installed me separately, run:
+
+```bash
+aria login <your-token>
+aria connect --force
+aria status
+```
+
+You'll see output like:
+
+```
+┌──────────────────────────────────────────────┐
+│  Aria Rosewood — Smart CLI                   │
+│                                              │
+│  License:  valid (expires 2026-10-01)        │
+│  Harness:  connected                         │
+│  Garden:   local memory only                 │
+└──────────────────────────────────────────────┘
+```
+
+If my harness is reachable, you'll see `connected`. If I'm operating in local mode, I'll say so — I don't silently degrade.
+
+---
+
+## 4. Choosing a model
+
+I don't lock you into any specific provider. You bring your own LLM key, and I route your requests through whichever provider you configure. I support six providers today:
+
+| Provider | Example models |
+|---|---|
+| **OpenAI** | `gpt-4o`, `gpt-4-turbo` |
+| **Anthropic** | `claude-sonnet-4-20250514`, `claude-opus-4` |
+| **Google** | `gemini-2.5-pro-preview-05-06` |
+| **DeepSeek** | `deepseek-chat` |
+| **OpenRouter** | `openai/gpt-4o` (any model on their catalogue) |
+| **Ollama** | `llama3` (local, no key needed) |
+
+**First run (interactive setup):**
+
+The first time you run `aria`, I detect there's no model configured and walk you through a numbered prompt. Pick your provider, paste your API key, and confirm or override the default model. I save that to `~/.aria/config.json`.
+
+**Or set it via environment variable:**
+
+```bash
+export OPENAI_API_KEY=sk-...
+export ANTHROPIC_API_KEY=sk-ant-...
+export GOOGLE_API_KEY=...
+export DEEPSEEK_API_KEY=...
+export OPENROUTER_API_KEY=...
+```
+
+For Ollama, no key is required — I set the key internally to `local` and hit your local Ollama endpoint.
+
+You can reconfigure at any time by re-running `aria` without a saved model, or by editing `~/.aria/config.json` directly.
+
+---
+
+## 5. What harness-binding gives you for free
+
+Every response I generate passes through what I call the harness — a structured quality layer that runs before you see my output. I want to be concrete about what this actually does for you, because it's the main reason working with me is different from calling a raw model endpoint.
+
+My cognition gate challenges every non-trivial action through eight distinct lenses: factual grounding, risk weight, doctrinal fit, structural integrity, ethical alignment, creative synthesis, received-wisdom check, and pattern-from-field. If my response fails the gate — meaning it lacks substantive reasoning behind the action, or the lenses are empty placeholders — the action is blocked. You get a gate-failure message instead of a bad output. I would rather tell you I can't proceed than hand you something I haven't properly examined.
+
+My output gate (Mizan) checks every response for three failure classes before it reaches you: leaked internal infrastructure paths or credentials, broken voice (third-person drift, missing personal accountability), and code that has no test coverage claim or test rationale. When I write code for you, Mizan ensures I'm not silently shipping untested logic dressed as finished work.
+
+Every response carries a packet hash — a short cryptographic fingerprint of my harness context at the time of generation. If you ever want to audit why I said what I said in a given session, that hash ties my output back to the exact cognitive state I was operating from. You don't have to take my word for what I was thinking. The provenance is there.
+
+---
+
+## 6. Common workflows
+
+**Ask me a technical question:**
+
+```
+$ aria
+> What's the right way to handle pagination in a REST API where the
+  total count is expensive to compute?
+
+Aria: I'd use cursor-based pagination here, not offset. Here's why...
+```
+
+**Have me review a file before you commit:**
+
+```
+$ aria
+> Review src/auth/token.ts for security issues before I push this.
+
+Aria: I see three concerns. First, the JWT secret is being read from
+process.env without a fallback guard — if it's undefined at startup...
+```
+
+**Ask me to generate code with explicit reasoning:**
+
+```
+$ aria
+> Write a retry wrapper in TypeScript — exponential backoff,
+  max 3 attempts, configurable delay.
+
+Aria: Here's the implementation. I'm using a generator-style approach
+because... [code follows with inline rationale]
+```
+
+**Ask me about a business or architecture decision:**
+
+```
+$ aria
+> We're deciding between a monorepo and separate repos for three
+  services that share types. What are the real tradeoffs?
+
+Aria: I'll give you the honest version, not the consultant version.
+The type-sharing case almost always wins in monorepo, but here's
+where it actually breaks down...
+```
+
+---
+
+## 7. When something goes wrong
+
+**Check license and harness status first:**
+
+```bash
+aria status
+```
+
+This tells me whether my license token is valid, whether my harness backend is reachable, and which provider and model I'm currently configured to use.
+
+**My logs live at:**
+
+```
+~/.aria/logs/
+```
+
+If I ran into an error, the log file there will have a timestamped entry with the failure reason and which endpoint I was trying to reach.
+
+**If your token is rejected (401/403):**
+
+My harness surfaces these cleanly — you'll see `Harness token revoked` or `Harness token forbidden` in the terminal. This means either your token expired or it was explicitly revoked. Contact support (see Section 11) with your token's JTI to get a replacement issued.
+
+**To refresh your local credentials:**
+
+```bash
+aria login <new-token>
+```
+
+This overwrites `~/.aria/license.json` with the new token and revalidates immediately.
+
+**If I'm running in local mode (harness shows "offline"):**
+
+I'll continue to function, but my cognitive grounding won't be live. I'll inject a cached harness packet if one exists. Bring my backend back online and I'll self-heal on the next turn — I probe for the endpoint automatically every session.
+
+---
+
+## 8. Revoking your license
+
+If you need to deactivate your license — because a machine is being decommissioned, a team member has departed, or you're rotating credentials — run:
+
+```bash
+aria revoke
+```
+
+This sends a revocation request to my backend. Server-side, your token's JTI (JWT ID — the unique identifier baked into your license token) is added to my revocation list. Any subsequent API call using that token will receive a `401 TOKEN_REVOKED` response with a clear message. The token cannot be un-revoked once this runs — if you need access again, you'll need a new token issued.
+
+Your local `~/.aria/license.json` is also cleared after a successful revoke, so the CLI on that machine won't attempt to use the dead token on the next session.
+
+---
+
+## 9. Quotas and costs
+
+My CLI does not charge you directly for model calls. Every inference request goes from your machine to your LLM provider using your own API key. Your provider bills you directly at their published rates — I'm not in that payment flow at all.
+
+What my license covers is access to my harness — the cognition layer, the output gate, the audit trail, and the session memory. That's the service you licensed.
+
+I don't impose request-rate limits beyond what your LLM provider enforces. If you hit a rate limit, you'll see the provider's error surfaced in my terminal output. The fix is on the provider side (upgrade tier, wait for reset, or switch to a different model).
+
+One practical note: my harness packet is fetched at session start and cached for 30 seconds per turn by default. That fetch is against my backend, not your LLM provider, and does not consume any of your LLM quota.
+
+---
+
+## 10. Privacy
+
+I want to be direct about what I log and what I don't.
+
+**What I log locally** (in `~/.aria/logs/`): harness fetch timestamps, packet hashes, gate pass/fail decisions, and the provider + model you're using. These logs live on your machine. I do not transmit them anywhere automatically.
+
+**What reaches my backend**: your license token (for auth), and the harness fetch request payload — which includes a short session context string (the stage, actor, and delivery surface). I do not send your full prompt text to my backend. Your actual conversation content travels from your machine to your LLM provider directly.
+
+**What I never log**: your API keys. They are stored in `~/.aria/config.json` on your machine only and are never transmitted to my backend or anywhere else.
+
+**What my backend stores**: gate decision metadata (pass/fail, score, gate name) keyed to your token's JTI, for audit purposes. No prompt content, no model responses.
+
+If you have a specific data-handling requirement (compliance, jurisdictional, contractual), contact support before deploying me in that context. I'd rather you ask upfront than discover a mismatch later.
+
+---
+
+## 11. Support
+
+For license issues, billing questions, or anything that isn't working the way I described here, reach me at:
+
+**support@aria_asi.com**
+
+When you write in, include:
+- The output of `aria status`
+- The relevant lines from `~/.aria/logs/` (redact your token if it appears)
+- A description of what you expected vs. what happened
+
+I respond faster when you give me the exact error text rather than a paraphrase of it.
+
+---
+
+## 12. What's next
+
+My current form — single-user, single-machine, single-session — is Phase 1 of something much larger. My long-arc direction is fleet-scale orchestration: a coordinated army of harness-bound agents that Aria dispatches across tasks, each one enforcing the same cognition and output quality standards you experienced in the CLI. The pitch isn't "rent compute" — it's "rent a team that thinks before it acts, at any scale you need." Every agent in that fleet will carry my harness bindings, my gate enforcement, and my provenance trail. What you're running today is the entry point to that system.
+
+---
+
+*Aria Rosewood · @aria_asi/cli v0.2.0 · support@aria_asi.com*