auramaxx 0.0.20 → 0.1.1

package/docs/api/wallets/data-portfolio.md

@@ -1,42 +0,0 @@
-# Wallet Data, Portfolio, Address Book, Bookmarks
-
-## Transaction Endpoints
-
-| Endpoint | Method | Auth | Notes |
-|---|---|---|---|
-| `/wallets/transactions` | GET | Token optional | Global transaction list |
-| `/wallet/:address/transactions` | GET | Token optional | Wallet transactions (DB path or on-chain fallback) |
-| `/wallet/:address/transactions` | POST | Bearer | Add manual transaction record |
-
-## Asset + Portfolio Endpoints
-
-| Endpoint | Method | Auth | Notes |
-|---|---|---|---|
-| `/wallet/:address/assets` | GET | Token optional | List tracked assets for wallet |
-| `/wallet/:address/asset` | POST | Bearer | Track/add asset |
-| `/wallet/:address/asset/:assetId` | DELETE | Bearer | Remove tracked asset |
-| `/portfolio` | GET | Token optional | Aggregated portfolio (chain/token rollups) |
-
-## Address Book Endpoints
-
-| Endpoint | Method | Auth | Notes |
-|---|---|---|---|
-| `/address-labels` | GET | Token optional | List labels (supports query filter) |
-| `/address-labels` | POST | Bearer | Create/update label |
-| `/address-labels/:id` | DELETE | Bearer | Delete label |
-
-## Bookmark Endpoints
-
-| Endpoint | Method | Auth | Notes |
-|---|---|---|---|
-| `/bookmarks` | GET | Token optional | List token bookmarks |
-| `/bookmarks` | POST | Bearer | Create bookmark |
-| `/bookmarks/:id` | DELETE | Bearer | Delete bookmark |
-
-## Related Public Data Endpoints
-
-For token metadata/intel lookups used in portfolio flows, see:
-
-- [`docs/api/system.md`](/api?doc=api/system.md)
-
-Compatibility note: wallet asset/transaction routes are available under both `/wallet/*` and `/wallets/*` prefixes.

package/docs/how-to-auramaxx/TROUBLESHOOTING.md

@@ -1,477 +0,0 @@
-# Troubleshooting
-
-Start with the Quick Fixes table for the fastest recovery path, then use deeper sections only if the first command fails.  
-Most issues are startup, auth, or configuration drift and can be resolved in a few checks.
-Windows users: command examples are primarily Bash; PowerShell equivalents are included where OS-specific tooling differs.
-
-## Quick Fixes
-
-| Problem | Fix |
-|---------|-----|
-| Server not running | `npx auramaxx` or `npx auramaxx start` (if UI is already open: `npx auramaxx restart`) |
-| Agent 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 |
-| Approval link not working | Use `http://localhost:4747/approve/<reqId>` (not `https://...`) |
-| "Nothing works" after startup or migrations | This often indicates data corruption; go to [Last Resort Reset (Destructive)](#last-resort-reset-destructive) |
-| Token expired / 401 error | Re-authenticate: `npx auramaxx auth request --agent-id <id> --profile dev`, approve, then `npx auramaxx auth claim <reqId> --json` |
-| `Cannot find module '.prisma/client/default'` | `cd "$(npm root -g)/auramaxx" && npx prisma generate --schema prisma/schema.prisma`, then `auramaxx start` |
-| Need startup/runtime diagnostics | `tail -f .logs/server.log .logs/dashboard.log` (PowerShell: `Get-Content .logs\server.log, .logs\dashboard.log -Wait`) |
-
----
-
-## 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:
-- macOS/Linux: `lsof -i :4242`
-- Windows PowerShell: `Get-NetTCPConnection -LocalPort 4242 | Select-Object -ExpandProperty OwningProcess`
-
----
-
-### 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`.
-
----
-
-### Windows native dependency caveat (better-sqlite3 / node-gyp)
-
-**Symptom:** `npm install`/`npm ci` fails on Windows with `better-sqlite3`, `node-gyp`, MSBuild, or Python errors.
-
-**Cause:** If prebuilt binaries are unavailable, native modules must compile locally.
-
-**Fix:**
-- Install Python 3 and ensure `py -3` works.
-- Install Visual Studio 2022 Build Tools with Desktop C++ workload (MSVC v143 + Windows SDK).
-- Re-run install: `npm ci` (or `npm install`).
-- Optional npm config:
-  - `npm config set msvs_version 2022`
-  - `npm config set python "py -3"`
-
----
-
-### 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, check for backups first:
-```bash
-npx auramaxx restore --list
-```
-If a recent backup exists, restore it:
-```bash
-npx auramaxx restore --latest
-```
-If no backups are available, reset the database (this preserves agent files and backups):
-```bash
-rm -f ~/.auramaxx/auramaxx.db
-npx auramaxx start
-```
-Windows PowerShell:
-```powershell
-Remove-Item "$env:USERPROFILE\.auramaxx\auramaxx.db" -ErrorAction SilentlyContinue
-npx auramaxx start
-```
-
-> **Note:** Backups are stored in `~/.aurabak/`, separate from the main data directory. Nuking `~/.auramaxx/` will not destroy your backups.
-
----
-
-### `Cannot find module '.prisma/client/default'` after update/install
-
-**Symptom:** Startup fails with an error like:
-`Cannot find module '.prisma/client/default'`
-
-**Cause:** Prisma generated runtime files are missing from the installed package.
-
-**Fix (global install):**
-```bash
-cd "$(npm root -g)/auramaxx"
-npx prisma generate --schema prisma/schema.prisma
-auramaxx start
-```
-
-**Fix (repo/local run):**
-```bash
-cd /path/to/aurawallet
-npx prisma generate --schema prisma/schema.prisma
-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`.
-- Windows note: if global install succeeds but command is still missing, ensure `%AppData%\npm` is on your `PATH`.
-
----
-
-### 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, request + claim:
-   - `npx auramaxx auth request --agent-id <id> --profile dev`
-   - `npx auramaxx auth claim <reqId> --json`
-
----
-
-### 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
-
-### Common auth flow (TLDR)
-
-1. Agent runs `npx auramaxx auth request --agent-id <id> --profile dev`.
-2. Human approves the `approveUrl`.
-3. Agent runs `npx auramaxx auth claim <reqId> --json`.
-4. Agent retries the original command.
-
-`reqId` usage:
-- Temp token: pass `--reqId <reqId>` once on the retry that consumes it.
-- Session token: claim with `reqId` once, then later calls can omit `reqId`.
-
----
-
-### 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 dev
-npx auramaxx auth claim <reqId> --json
-```
-Approve the request in the dashboard, then claim and retry.
-
----
-
-### 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 dev
-npx auramaxx auth claim <reqId> --json
-```
-Approve in the dashboard, then claim and retry. See [AUTH.md](../ai-agents-workflow/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 dev
-npx auramaxx auth claim <reqId> --json
-```
-Approve in the dashboard, then claim and retry with the new token.
-
----
-
-### Auth claim stays "pending" forever
-
-**Symptom:** `npx auramaxx auth claim <reqId>` keeps returning pending.
-
-**Cause:** No one approved the request. Approval must happen in the dashboard, Telegram, or CLI.
-
-**Fix:**
-- Open `http://localhost:4747` (or the direct `approveUrl`) and approve the pending request.
-- Or check Telegram if adapter is configured.
-- Re-run claim: `npx auramaxx auth claim <reqId> --json`.
-- The request times out after 2 minutes by default.
-
----
-
-### Approval link opens but does not work
-
-**Symptom:** Approval page fails to load, shows SSL error, or redirects incorrectly.
-
-**Cause:** Using `https://` instead of `http://` for local dashboard approvals.
-
-**Fix:**
-- Use `http://localhost:4747/approve/<reqId>` (must be `http`, not `https`).
-- If your link starts with `https://`, replace it with `http://`.
-- Then retry claim: `npx auramaxx auth claim <reqId> --json`.
-
----
-
-## Agent & Credentials
-
-### Agent 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 agent password.
-- Or run `npx auramaxx unlock`.
-- For headless/automated environments: `AGENT_PASSWORD=... npx auramaxx start --headless`.
-
----
-
-### "Database exists but agent files missing"
-
-**Symptom:** Startup prompts about missing agent files.
-
-**Cause:** Agent JSON files were deleted while `auramaxx.db` remained (manual partial delete or older reset flow).
-
-**Fix:**
-- If this happened after an intentional nuke, rerun `npx auramaxx` and continue setup (`init`).
-- If this was accidental and you have no backup of the old agent files, choose **wipe** when prompted and re-setup.
-- Old encrypted data cannot be recovered without the original agent files.
-
----
-
-### Agent deleted but unlock still requested
-
-**Symptom:** After deleting agent, the server still asks to unlock.
-
-**Cause:** Agent files are in a different location than expected.
-
-**Fix:** Check the data path. Default is `~/.auramaxx` (not `~/.aurawallet`). Delete agent files from the correct location:
-```bash
-ls ~/.auramaxx/agent-*.json
-```
-Windows PowerShell:
-```powershell
-Get-ChildItem "$env:USERPROFILE\.auramaxx\agent-*.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 agent is locked.
-
-**Fix:**
-1. Check agent 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>
-```
-Windows PowerShell:
-```powershell
-Get-NetTCPConnection -LocalPort 4242,4747 | Select-Object LocalPort, OwningProcess, State
-Stop-Process -Id <PID> -Force
-```
-
----
-
-### 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:
-   - macOS/Linux: `rm -f ~/.auramaxx/auramaxx.db && npx auramaxx start`
-   - Windows PowerShell: `Remove-Item "$env:USERPROFILE\.auramaxx\auramaxx.db" -ErrorAction SilentlyContinue; npx auramaxx start`
-4. If dependency-related:
-   - macOS/Linux: `rm -rf node_modules && npm install`
-   - Windows PowerShell: `Remove-Item .\node_modules -Recurse -Force -ErrorAction SilentlyContinue; 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 agent.
-
----
-
-## Last Resort Reset (Destructive)
-
-⚠️ This permanently removes local Aura data (agent files, database, credentials, logs, config). All encrypted data will be unrecoverable.
-
-Before nuking, check if you can restore from a backup:
-```bash
-npx auramaxx restore --list
-```
-
-If no backup helps, nuke and re-setup:
-```bash
-npx auramaxx nuke
-npx auramaxx start
-```
-
-> **Your backups are safe.** Backups live in `~/.aurabak/`, not `~/.auramaxx/`, so the nuke above won't touch them.
-
----
-
-## Still stuck?
-
-Run full diagnostics and share the output:
-```bash
-npx auramaxx doctor --json
-```
-
-See also:
-- [Setup guide](../quickstart/AGENT_SETUP.md)
-- [Auth reference](../ai-agents-workflow/AUTH.md)
-- [MCP setup](../ai-agents-workflow/MCP.md)
-- [CLI reference](../ai-agents-workflow/CLI.md)

package/docs/how-to-auramaxx/WORKING_WITH_SECRETS.md

@@ -1,96 +0,0 @@
-# Working With Secrets
-
-Use this guide to read, write, and inject secrets without pasting plaintext credentials into prompts or code.  
-Start with `get`, `set`, and `list`, then use `inject` for controlled command execution.
-
-## Getting Secrets
-
-In local socket mode, `auramaxx get` confirms the credential can be decrypted (`SECRET DECRYPTED`), but it does **not** export an env var into your parent shell.
-Use `auramaxx inject` when you want a value available to a command.
-
-```bash
-# local socket read: verifies/decrypts
-auramaxx get DONTLOOK
-
-# command-scoped injection (recommended)
-auramaxx get DONTLOOK -- printenv AURA_DONTLOOK
-
-# unsafe plaintext debug output (prints secret in terminal)
-auramaxx get DONTLOOK --danger-plaintext
-
-# custom env var name:
-auramaxx inject DONTLOOK --env AURA_DONTNOTE -- printenv AURA_DONTNOTE
-```
-
-With explicit token auth (for example `AURA_TOKEN=...`), `auramaxx get` can print primary fields or full payloads. Use flags for specific fields or full payloads:
-
-```bash
-auramaxx get OURSECRET                     # primary value field only
-auramaxx get OURSECRET --field username    # specific field
-auramaxx get OURSECRET --json              # full credential payload
-auramaxx get OURSECRET --totp              # current TOTP code only
-auramaxx get OURSECRET --agent primary     # restrict match to a agent
-auramaxx get OURSECRET                     # if name is ambiguous, first match is selected by default
-auramaxx get OURSECRET --first             # compatibility flag (same behavior)
-auramaxx get OURSECRET --reqId <reqId>     # retry with claimed one-shot approval token
-```
-
-## Setting Secrets
-
-### Fast Path
-
-```bash
-auramaxx set OURSECRET 123
-```
-
-### Helper Flags
-
-```bash
-# set explicit type/field
-auramaxx set GITHUB_LOGIN hunter2 --type login --field password
-
-# attach tags
-auramaxx set STRIPE_KEY sk_live_123 --type apikey --tags prod,api
-
-# set extra structured fields
-auramaxx set GITHUB_LOGIN hunter2 --type login --field password --username alice
-```
-
-MCP path:
-
-- call `put_secret` with `name: "OURSECRET"` and `value: "123"`
-
-## Listing Secrets
-
-### Fast Path
-
-```bash
-auramaxx list
-```
-
-### Helper Flags
-
-```bash
-# filter by credential name/title substring
-auramaxx list --name github
-
-# filter by field key/value substring (best effort; reads credential payloads)
-auramaxx list --field token
-
-# filter by agent name or id
-auramaxx list --agent primary
-auramaxx list --agent agent-2
-
-# combine filters + structured output
-auramaxx list --agent primary --name github --json
-```
-
-MCP path:
-
-- call `list_secrets`
-
-## If It Fails
-
-1. Check runtime health: `auramaxx status`
-2. If agent is locked: unlock in dashboard (`http://localhost:4747`) or run `auramaxx unlock`
-3. If MCP call gets permission denied: follow [AGENT_SETUP.md](../quickstart/AGENT_SETUP.md), then [AUTH.md](../ai-agents-workflow/AUTH.md)

package/docs/how-to-auramaxx/share-secret.md

@@ -1,74 +0,0 @@
-# Share a Secret (CLI + UI)
-
-Share with a GitHub Gist link when possible; use local links only when the recipient can reliably reach your host/network.  
-Use CLI for repeatable automation and UI for one-off/manual review flows.
-
----
-
-## Prerequisite: GitHub CLI auth (for Gist sharing)
-
-Check auth:
-
-```bash
-gh auth status
-```
-
-If not authenticated:
-
-```bash
-gh auth login
-```
-
-If `gh` is missing, install GitHub CLI first, then authenticate.
-
----
-
-## CLI sharing
-
-### Recommended command
-
-```bash
-auramaxx agent share OPENAI_KEY --expires-after 24h
-```
-
-### Alias path (same behavior)
-
-```bash
-auramaxx share OPENAI_KEY --expires-after 24h
-```
-
-### What to expect
-
-- If GitHub auth is available, CLI generates a share via Gist and returns a shareable link.
-- If GitHub/Gist path is unavailable, use local-link fallback (see below).
-
----
-
-## UI sharing
-
-1. Open Agent and select a credential.
-2. Click **SHARE** in credential detail.
-3. In the share modal:
-   - Prefer **SHARE GIST** (recommended for remote recipients).
-   - Use local link only when recipient can reach your host/network.
-
----
-
-## Local-link limitation (important)
-
-A local link is often **not reachable** by remote recipients.
-
-Use local links only when:
-- recipient is on the same network, or
-- you provide a secure tunnel/network path.
-
----
-
-## Tunnel/network fallback options
-
-If Gist sharing is unavailable and recipient is remote, use one of these:
-
-- Cloudflare Tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
-- Tailscale: https://tailscale.com/kb
-
-These options can make local-hosted share endpoints reachable in a controlled way.