auramaxx 0.0.1

package/skills/auramaxx/docs/CLI.md

@@ -0,0 +1,130 @@
+# CLI
+
+## Commands
+
+The most common commands. All use the `aura` alias (or `npx auramaxx`).
+
+| Command | Description |
+|---------|-------------|
+| `aura get <name>` | Read a credential (`--json` for full payload) |
+| `aura set <name> <value>` | Create or update a secret |
+| `aura list` | List credential names |
+| `aura diary write --entry "<text>"` | Append an authenticated daily diary entry |
+| `aura share <name>` | Create a shareable secret gist link |
+| `aura inject <name> [-- <cmd>]` | Save to env var and optionally run command |
+| `aura del <name>` | Delete a credential |
+
+> **Note:** `aura get` returns encrypted ciphertext by default — this is a protected route.
+> To decrypt and print a value, use `aura inject <name> -- printenv AURA_SECRET`.
+> To pass a secret to a command under a custom env var: `aura inject <name> --env MY_VAR -- <your-command>`.
+
+## First Success (Run In Order)
+
+```bash
+aura status
+aura list
+aura set OURSECRET 123
+aura get OURSECRET
+aura share OURSECRET --expires-after 24h
+```
+
+If `status` fails, see [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+`status` checks both services: API server (`http://localhost:4242`) and dashboard UI (`http://localhost:4747`).
+
+## Admin Commands
+
+Essential admin commands for setup and maintenance.
+
+| Command | Description |
+|---------|-------------|
+| `aura start` | Start Aura services (includes first-run bootstrap) |
+| `aura status` | Check runtime health |
+| `aura init` | Advanced/recovery setup flow (most users should run `start`) |
+| `aura mcp` | Start MCP server for Claude Code, Cursor, etc. |
+| `aura skill` | Install AuraMaxx skills for Claude/Codex/OpenClaw |
+| `aura auth` | Request/poll agent auth approvals |
+
+Run `aura --help --all` to see all commands including advanced admin (stop, lock, unlock, doctor, restore, etc.).
+
+## Stopping Servers
+
+```bash
+aura stop
+```
+
+Stops all running AuraMaxx processes:
+
+- **Wallet server** (`server/index.ts` on port 4242)
+- **Cron server** (`server/cron/index.ts` — balance sync, price sync)
+- **Dashboard** (`next dev` on port 4747)
+
+Also cleans up temp files (CLI lock file, Unix socket).
+
+This does **not** affect the MCP server — that runs in its own stdio process managed by the client (Claude Code, Cursor, etc.) that started it.
+
+## Examples
+
+```bash
+# Check services
+aura status
+
+# Credentials
+aura list                                                 # List credential names
+aura get OURSECRET                                        # Read a credential
+aura set OURSECRET 123                                    # Create or update a credential value
+aura set GITHUB_LOGIN hunter2 --type login                # Store as login credential (password field)
+aura share OURSECRET --expires-after 24h                  # Create a shareable secret gist link
+aura del OURSECRET                                        # Delete a credential
+
+# Inject secret into a command
+aura inject DONTLOOK --env HIDETHIS -- printenv HIDETHIS  # Execute command with injected secret env var
+
+# Auth and approvals
+aura auth request --agent-id codex --profile strict
+aura auth request --profile strict --action '{"endpoint":"/send","method":"POST","body":{"to":"0x...","amount":"0.01"}}'
+aura auth poll <requestId> --secret <secret>
+aura diary write --entry "Heartbeat: no pending requests, sync ok"
+
+# Advanced
+aura api GET /health --no-auth                            # Call any API endpoint
+aura doctor                                               # Run diagnostics
+```
+
+Sensitive output defaults:
+
+- Sensitive fields return encrypted output by default.
+- To auto-decrypt sensitive output, set `AUTO_DECRYPT=true` and `AURA_VAULT_PASSWORD=<password>`.
+
+## All Commands
+
+Full list visible via `aura --help --all`. Summary:
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start Aura services (includes bootstrap/setup) |
+| `stop` | Stop running servers |
+| `status` | Check runtime health |
+| `init` | Advanced/recovery setup flow |
+| `unlock` / `lock` | Unlock or lock vaults |
+| `mcp` | Start MCP server for Claude Code, Cursor, etc. |
+| `skill` | Install AuraMaxx skills for agents |
+| `auth` | Request/poll agent auth approvals |
+| `diary` | Append daily diary entries (auth-aware) |
+| `actions` | Internal: human actions and token management (use `auth` instead) |
+| `api` | Call any wallet API endpoint from CLI |
+| `doctor` | Run diagnostics |
+| `restore` | Restore backup + run migrations |
+| `app` | Manage installed apps |
+| `apikey` | List/validate/set/delete API keys |
+| `env` | Load env vars from vault via .aura file |
+| `shell-hook` | Auto-load .aura env vars on cd (like direnv) |
+| `experimental` | Toggle dev feature flags |
+| `cron` | Run cron server standalone |
+| `secret` | Run commands with injected secret env vars |
+| `token` | Preview profile-based token policy |
+| `wallet` | Wallet API wrappers (status, assets, swap, send, fund) |
+
+## Next Steps
+
+- Builder / AI integration -> [MCP.md](MCP.md)
+- Operator / Security -> [security.md](security.md)

package/skills/auramaxx/docs/MCP.md

@@ -0,0 +1,122 @@
+# MCP
+
+AuraMaxx MCP server exposes credential vault and wallet APIs to MCP clients over stdio.
+
+## Start
+
+```bash
+auramaxx
+auramaxx mcp
+```
+
+`auramaxx` starts the API server on `http://localhost:4242` and dashboard UI on `http://localhost:4747`.
+
+Auto-configure local IDE MCP files:
+
+```bash
+auramaxx mcp --install
+```
+
+## Per-client setup (exact locations + JSON)
+
+Use the client-specific setup guide:
+
+- `docs/AGENT_SETUP.md`
+
+It includes exact config locations, copy-paste JSON, restart steps, and quick verification for Cursor, Codex, Claude Desktop, OpenClaw, and generic MCP clients.
+
+## MCP Resources
+
+- `docs://api`
+- `docs://auth`
+- `docs://guide`
+
+## Tools (12)
+
+| # | Tool | Description |
+|---|------|-------------|
+| 1 | `get_secret` | Look up a credential by name/tag, decrypt and return all fields |
+| 2 | `put_secret` | Store a new credential (note type) in the default vault |
+| 3 | `list_secrets` | List credentials with optional query/tag/vault/lifecycle filters |
+| 4 | `del_secret` | Delete a credential by name |
+| 5 | `inject_secret` | Read a credential and inject its value as an env var (or into a child process) |
+| 6 | `share_secret` | Create a time-limited shareable link for a credential |
+| 7 | `api` | Generic AuraMaxx API caller (any endpoint, any method) |
+| 8 | `auth` | Request an authenticated session token (ephemeral RSA + human approval polling) |
+| 9 | `get_token` | Check if session has an active token (poll after `auth` for approval status) |
+| 10 | `status` | Get server setup/unlock health state |
+| 11 | `start` | Start the AuraMaxx server in headless mode if not already running |
+| 12 | `write_diary` | Append an entry to a daily diary note |
+
+`api` is the generic fallback for any endpoint; the other tools provide typed, higher-level operations.
+
+## Skill Install
+
+Install AuraMaxx skills for your AI agents:
+
+```bash
+npx auramaxx skill
+```
+
+This auto-installs skills for Claude, Codex, and OpenClaw. Verify with:
+
+```bash
+npx auramaxx skill --doctor
+```
+
+If auto-install fails, use the fallback:
+
+```bash
+cd <your-codebase> && npx -y skills add Aura-Industry/auramaxx
+```
+
+For a pushed GitHub ref (branch or commit):
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo Aura-Industry/auramaxx \
+  --path skills/auramaxx \
+  --ref <branch-or-commit>
+```
+
+`write_diary` appends to `{YYYY-MM-DD}_LOGS` notes using agent vault by default, with fallback to primary vault.
+Diary notes use canonical note field key `content` (`value` is accepted as a legacy alias and normalized).
+
+## Credential read flow via MCP
+
+1. Obtain token (`auth` tool, or socket bootstrap, or `AURA_TOKEN` env var)
+2. If using `auth`, poll with `get_token` until `hasToken: true` (approval is async)
+3. Call `get_secret` (high-level) or `api` POST `/credentials/:id/read` (low-level)
+4. Decrypt returned `encrypted` payload in your MCP host
+
+Note:
+- Typed tools (`get_secret`, `put_secret`, `del_secret`, `share_secret`, `inject_secret`, `write_diary`) use the active MCP token directly.
+- Typed helpers have **built-in 403 escalation** — on permission denied they automatically return a structured `requiresHumanApproval` response. You do not need to detect 403s yourself for typed tools.
+- The generic `api` tool does **not** auto-escalate — on 403, check the error response and request appropriate permissions via `auth`.
+
+## 403 escalation ladder
+
+1. Call the typed tool or `api`.
+2. If 403, typed tools auto-return a `nextStep` with the `api` call params — follow it.
+   For `api`, request a new token via `auth` with the required profile/permissions.
+3. Tell the human to approve in the dashboard at `http://localhost:4747` (or via Telegram/CLI adapter).
+4. **Never** retry the same blocked call without escalating first.
+
+## Safety pattern
+
+- Start with least privilege (`secret:read`, narrow `credentialAccess.read` scopes)
+- Typed tools auto-escalate on 403; for `api`, use `auth` to request a new token
+- Tell the human to approve at `http://localhost:4747`
+- Avoid broad long-lived tokens
+
+## Example call
+
+```json
+{
+  "method": "POST",
+  "endpoint": "/credentials/cred-123/read",
+  "body": {}
+}
+```
+
+See also: [GETTING_SECRETS](./external/HOW_TO_AURAMAXX/GETTING_SECRETS.md), [AUTH](AUTH.md), and [Troubleshooting](TROUBLESHOOTING.md).

package/skills/auramaxx/docs/TROUBLESHOOTING.md

@@ -0,0 +1,357 @@
+# Troubleshooting
+
+## Quick Fixes
+
+| Problem | Fix |
+|---------|-----|
+| Server not running | `npx auramaxx` or `npx auramaxx start` |
+| Vault locked after restart | Open `http://localhost:4747` and enter your password, or run `npx auramaxx unlock` |
+| `auramaxx: command not found` | Open a new terminal, or use `npx auramaxx` directly |
+| MCP tools missing in agent | `npx auramaxx mcp --install`, then restart your IDE/agent |
+| Token expired / 401 error | Re-authenticate: `npx auramaxx auth request --agent-id <id> --profile strict` |
+
+---
+
+## Setup & Onboarding
+
+### Server won't start / connection refused
+
+**Symptom:** Any CLI command returns "connection refused" or "fetch failed".
+
+**Cause:** The Aura server isn't running.
+
+**Fix:**
+```bash
+npx auramaxx start
+```
+Then retry your command. If port 4242 is in use, check for other processes: `lsof -i :4242`.
+
+---
+
+### Dashboard not loading at localhost:4747
+
+**Symptom:** Browser shows "connection refused" or blank page at `http://localhost:4747`.
+
+**Cause:** Server started in headless mode, or hasn't finished starting yet.
+
+**Fix:**
+- Wait a few seconds and refresh.
+- If started with `--headless`, the dashboard is intentionally disabled. Restart without `--headless`: `npx auramaxx start`.
+- Check server status: `npx auramaxx status`.
+
+---
+
+### First run hangs or shows no output
+
+**Symptom:** Running `npx auramaxx` for the first time shows nothing for several seconds.
+
+**Cause:** npm is downloading the package and dependencies. This is normal on first run.
+
+**Fix:** Wait 30–60 seconds. If it takes longer, check your internet connection. Run with `--debug` for verbose output: `npx auramaxx start --debug`.
+
+---
+
+### Database migration errors on startup
+
+**Symptom:** Errors mentioning Prisma, migrations, or database schema during start.
+
+**Cause:** Database schema is out of date, or the database file is corrupted.
+
+**Fix:**
+```bash
+npx auramaxx start --debug
+```
+If migration errors persist, try resetting the database (this preserves vault files):
+```bash
+rm -f dev.db
+npx auramaxx start
+```
+
+---
+
+## CLI Commands
+
+### `auramaxx: command not found`
+
+**Symptom:** Running `auramaxx` or `aura` returns "command not found".
+
+**Cause:** The CLI isn't installed globally, or the shell alias wasn't loaded.
+
+**Fix:**
+- Use `npx auramaxx` instead (always works).
+- Or open a new terminal (aliases are loaded on shell start).
+- Or run `npx auramaxx doctor --fix` to install shell fallbacks.
+- Or install globally: `npm install -g auramaxx`.
+
+---
+
+### Unknown command error
+
+**Symptom:** `Unknown command: <name>` when running a CLI command.
+
+**Cause:** Typo, or the command doesn't exist. Some commands are only visible with `--all`.
+
+**Fix:**
+```bash
+npx auramaxx --help --all
+```
+
+---
+
+### `npx auramaxx doctor` shows failures
+
+**Symptom:** Doctor reports `FAIL` checks in red.
+
+**Cause:** Various — each check has its own remediation.
+
+**Fix:** Read the `remediation` line for each failed check. Common ones:
+- "Run: npx auramaxx" → server isn't running
+- "Export AURA_TOKEN" → no token set for explicit auth checks
+- "Run: npx auramaxx doctor --fix" → shell fallback missing
+
+---
+
+## MCP Integration
+
+### MCP tools not showing up in IDE
+
+**Symptom:** After adding MCP config, your agent/IDE doesn't see Aura tools.
+
+**Cause:** MCP config not saved correctly, or IDE not restarted after config change.
+
+**Fix:**
+1. Run `npx auramaxx mcp --install` to auto-configure.
+2. Restart your IDE/agent completely (not just reload).
+3. Verify config exists: check `.mcp.json` or your IDE's MCP config file.
+4. Test manually: `npx auramaxx mcp` should start without errors.
+
+---
+
+### MCP auth fails / tools return 401
+
+**Symptom:** MCP tools exist but return authentication errors.
+
+**Cause:** Server restarted (tokens are memory-only) or token expired.
+
+**Fix:**
+1. Make sure the server is running: `npx auramaxx status`.
+2. If using socket auth, ensure the server was started by the same user.
+3. If using token auth, re-request: `npx auramaxx auth request --agent-id <id> --profile strict`.
+
+---
+
+### MCP config JSON parse error
+
+**Symptom:** IDE shows "invalid JSON" or fails to load MCP config.
+
+**Cause:** Malformed JSON in the MCP config file (trailing comma, missing bracket).
+
+**Fix:** Run `npx auramaxx doctor` — it checks MCP config files for parse errors. Fix the JSON syntax in the reported file.
+
+---
+
+## Auth & Tokens
+
+### 401 "Invalid or expired token"
+
+**Symptom:** API calls return 401 with "Invalid or expired token".
+
+**Cause:** Server was restarted (all tokens are memory-only) or the token TTL expired.
+
+**Fix:**
+```bash
+npx auramaxx auth request --agent-id <your-agent-id> --profile strict
+```
+Approve the request in the dashboard, then use the new token.
+
+---
+
+### 403 "Insufficient permissions"
+
+**Symptom:** API call returns 403 with "Insufficient permissions".
+
+**Cause:** Your token doesn't have the required permission for this operation.
+
+**Fix:** The 403 response includes structured guidance with a `nextStep` field — follow it. Typically:
+```bash
+npx auramaxx auth request --profile strict
+```
+Approve in the dashboard, then retry. See [AUTH.md](AUTH.md) for permission names.
+
+---
+
+### 403 "Amount exceeds spending limit"
+
+**Symptom:** Transaction returns 403 with spending limit error.
+
+**Cause:** The token's spending budget for this operation type is exhausted.
+
+**Fix:** Follow the `nextStep` in the 403 response, or request a new token:
+```bash
+npx auramaxx auth request --profile strict
+```
+Approve in the dashboard, then retry with the new token.
+
+---
+
+### Auth request stays "pending" forever
+
+**Symptom:** `npx auramaxx auth request` keeps polling but never completes.
+
+**Cause:** No one approved the request. Approval must happen in the dashboard, Telegram, or CLI.
+
+**Fix:**
+- Open `http://localhost:4747` and approve the pending request.
+- Or check Telegram if adapter is configured.
+- The request times out after 2 minutes by default.
+
+---
+
+## Vault & Credentials
+
+### Vault locked after server restart
+
+**Symptom:** Commands return "Cold wallet must be unlocked" or 401.
+
+**Cause:** Unlock state is memory-only — it resets on every server restart.
+
+**Fix:**
+- Open `http://localhost:4747` and enter your vault password.
+- Or run `npx auramaxx unlock`.
+- For headless/automated environments: `VAULT_PASSWORD=... npx auramaxx start --headless`.
+
+---
+
+### "Database exists but vault files missing"
+
+**Symptom:** Startup prompts about missing vault files.
+
+**Cause:** Vault JSON files were deleted but the database still references them.
+
+**Fix:** If you have no backup of the old vault files, choose "wipe" when prompted and re-setup. Old encrypted data cannot be recovered without the original vault files.
+
+---
+
+### Vault deleted but unlock still requested
+
+**Symptom:** After deleting vault, the server still asks to unlock.
+
+**Cause:** Vault files are in a different location than expected.
+
+**Fix:** Check the data path. Default is `~/.auramaxx` (not `~/.aurawallet`). Delete vault files from the correct location:
+```bash
+ls ~/.auramaxx/vault-*.json
+```
+
+---
+
+### Credential not found / .aura mapping fails
+
+**Symptom:** `npx auramaxx env run` or `.aura` mapping reports missing credentials.
+
+**Cause:** The credential name in `.aura` doesn't match any stored credential, or the vault is locked.
+
+**Fix:**
+1. Check vault is unlocked: `npx auramaxx status`.
+2. List credentials: `npx auramaxx list`.
+3. Verify `.aura` file names match: `npx auramaxx env check`.
+
+---
+
+## Agent & Skills
+
+### Skill install fails
+
+**Symptom:** `npx auramaxx skill` reports failures for one or more targets.
+
+**Cause:** Permission denied on target directory, or source skill files missing.
+
+**Fix:**
+- Check the error message for which target failed and why.
+- Fallback: `cd <your-codebase> && npx -y skills add Aura-Industry/auramaxx`.
+- Verify with: `npx auramaxx skill --doctor`.
+
+---
+
+### Agent can't find skills after install
+
+**Symptom:** Agent (Claude/Codex/OpenClaw) doesn't use Aura skills even after `skill` install.
+
+**Cause:** Agent needs to be restarted to pick up new skills, or skill was installed to wrong directory.
+
+**Fix:**
+1. Run `npx auramaxx skill --doctor` to verify install paths.
+2. Restart the agent session.
+3. Check the agent's skill directory matches the installed path.
+
+---
+
+## Runtime & Server
+
+### Port 4242 or 4747 already in use
+
+**Symptom:** Server fails to start with "address already in use" error.
+
+**Cause:** Another instance of Aura or another process is using the port.
+
+**Fix:**
+```bash
+npx auramaxx stop
+npx auramaxx start
+```
+If that doesn't work, find and kill the process:
+```bash
+lsof -i :4242
+kill <PID>
+```
+
+---
+
+### Server crashes on startup
+
+**Symptom:** Server starts but immediately exits with an error.
+
+**Cause:** Various — dependency issue, database corruption, or configuration error.
+
+**Fix:**
+1. Run with debug output: `npx auramaxx start --debug`.
+2. Run diagnostics: `npx auramaxx doctor`.
+3. If database-related: `rm -f dev.db && npx auramaxx start`.
+4. If dependency-related: `rm -rf node_modules && npm install`.
+
+---
+
+### WebSocket connection drops
+
+**Symptom:** Dashboard shows "disconnected" or real-time updates stop.
+
+**Cause:** Server restarted, network interruption, or browser tab was inactive too long.
+
+**Fix:** Refresh the dashboard page. If the server restarted, you'll need to re-unlock the vault.
+
+---
+
+## Last Resort Reset (Destructive)
+
+⚠️ This permanently removes local vault files. All encrypted data will be unrecoverable.
+
+```bash
+rm -f ~/.auramaxx/vault-*.json ~/.auramaxx/cold.json
+rm -f dev.db
+npx auramaxx
+```
+
+---
+
+## Still stuck?
+
+Run full diagnostics and share the output:
+```bash
+npx auramaxx doctor --json
+```
+
+See also:
+- [Setup guide](AGENT_SETUP.md)
+- [Auth reference](AUTH.md)
+- [MCP setup](MCP.md)
+- [CLI reference](CLI.md)