atris 3.12.0 → 3.13.0

package/README.md

@@ -27,7 +27,7 @@ Then read the workspace's `atris/atris.md` and follow it exactly. `atris.md` is
 
 | File | Purpose |
 |------|---------|
-| `atris/atris.md` | God file. Protocol and source of truth |
+| `atris/atris.md` | Main instructions for agents working in this repo |
 | `atris/MAP.md` | Navigation index with file:line refs |
 | `atris/TODO.md` | Shared task queue |
 | `atris/logs/YYYY/YYYY-MM-DD.md` | Daily log, inbox, notes, completions |
@@ -67,7 +67,7 @@ atris
 
 `atris init` scaffolds the workspace, including `atris/wiki/`. `atris` loads context and hands the workflow off to `atris/atris.md`.
 
-If you're still shaping the idea, use `atris brainstorm`. If you want Atris to keep cycling, use `atris run` or `atris autopilot`. If you want the repo brain kept honest, use `atris loop`. `atris activate` now surfaces wiki state from `atris/wiki/STATUS.md` when it exists.
+If you're still shaping the idea, use `atris brainstorm`. If you want Atris to keep cycling, use `atris run` or `atris autopilot`. If you want project memory checked for stale pages and missing context, use `atris loop`. `atris activate` surfaces wiki state from `atris/wiki/STATUS.md` when it exists.
 
 Core loop: `plan` -> `do` -> `review`
 
@@ -84,9 +84,9 @@ atris business onboard --website https://blondish.world --contact "Joel Zimmerma
 atris align --fix
 ```
 
-That creates the cloud business, writes `.atris/business.json`, initializes `.atris/state/` for events, episodes, and scorecards, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter team lanes, a default recap artifact, and a first-loop starter queue in `atris/TODO.md`.
+That creates the cloud business, writes `.atris/business.json`, initializes `.atris/state/` for events and run history, and scaffolds the local `atris/` workspace under `~/arena/atris-business/<slug>/` with starter roles, a default recap template, and an initial task queue in `atris/TODO.md`.
 
-If you do not have a neat source pack yet, `atris business onboard` is the low-friction intake step: give it a website, a named human, a few notes, or even just run it in a folder with loose files, and it seeds raw intake, a starter brief, a first loop, a safe next action, and an operator one-pager for you.
+If you do not have a neat source pack yet, `atris business onboard` is the easiest intake step: give it a website, a named human, a few notes, or run it in a folder with loose files. Atris turns that into raw intake, a starter brief, a first workflow, a safe next action, and a short operator brief.
 
 You can also use bare input:
 
@@ -120,26 +120,27 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 | `atris ingest` | Stage raw evidence into `atris/context/` and compile into `atris/wiki/` |
 | `atris loop` | Refresh wiki health, stale/orphan signals, and next ingest candidates |
 | `atris wiki` | Full wiki namespace: ingest, query, lint, search, log, and loop |
-| `atris experiments` | Run Karpathy-style keep/revert packs |
+| `atris receipt` | Save evidence from an agent run |
+| `atris experiments` | Run small experiments and compare results |
 
 ## Built-In Systems
 
 - `atris learn` stores structured project memory in `atris/learnings.jsonl`
 - `atris wiki` keeps repo memory in `atris/wiki/` by default, with `--cloud` when you want the remote workspace path
 - `atris ingest` now stages local source packs under `atris/context/_ingest/`, writes a manifest receipt, and refreshes `atris/wiki/STATUS.md` plus `log.md`
-- `atris wiki --private` uses `.atris/presidio/` for local-only sensitive notes and operating memory
+- `atris wiki --private` stores local-only sensitive notes under `.atris/presidio/`
 - `atris loop` refreshes `atris/wiki/STATUS.md` and `atris/wiki/log.md`, flags stale/orphan pages, and suggests the next ingest
 - `atris activate` loads the current wiki status so the next session starts with project memory, not just tasks
-- `atris experiments` runs Karpathy-style keep/revert loops in `atris/experiments/`
+- `atris experiments` runs small test packs in `atris/experiments/`
 - `atris pull` and `atris push` sync cloud workspaces and journals
 
 ## Verifiable Feedback Loop
 
 Under the hood, Atris can keep score on real repo work.
 
-- Endgame tasks can carry a `Verify:` command, so work can end on a deterministic check instead of pure prose.
-- `atris autopilot` can run that check after review, record a reward in the journal, and append a local scorecard when a horizon closes.
-- Future horizon picks can weight against recent scorecards, so the loop learns from repo-local history without claiming model retraining.
+- Tasks can carry a `Verify:` command, so work can end on a deterministic check instead of pure prose.
+- `atris autopilot` can run that check after review and record the result in the journal.
+- Future task picks can use recent results, so Atris learns from repo-local history without claiming model retraining.
 
 ## Benchmark Harness
 
@@ -167,7 +168,7 @@ What to inspect:
 - receipts land in `atris/experiments/endstate-baseline/artifacts/` and
   `atris/experiments/endstate-stack/artifacts/`
 - scores append to each pack's `results.tsv`
-- `atris experiments compare endstate` prints the latest side-by-side scorecard
+- `atris experiments compare endstate` prints the latest side-by-side comparison
 - `atris experiments replay endstate` runs the full public dry-run rehearsal
 - the benchmark contract lives at `atris/features/endstate/contract.md`
 - the verification log lives at `atris/features/endstate/validate.md`
@@ -198,7 +199,7 @@ For Codex, copy any skill folder into `~/.codex/skills/`.
 ## v3.2.0
 
 - **Staleness gate** — tasks tagged `[unverified]` are skipped at the moment of use, not pruned eagerly. Three-state model: actionable / unverified / deleted.
-- **Lesson gate** — `isLessonResolved` checks whether a lesson already shipped before proposing new horizons from it. Prevents the loop from re-solving solved problems.
+- **Lesson gate** — `isLessonResolved` checks whether a lesson already shipped before proposing new work from it. Prevents the loop from re-solving solved problems.
 - **`atris release`** — new command: tags the version, bumps package.json, creates a GitHub release, and drafts a `/launch` post in one shot.
 - **Shell injection fix** — `checkStaleness` switched from `execSync` string interpolation to `execFileSync` with args arrays. Markdown-derived content (task titles, inbox items) no longer reaches a shell.
 - **Codex hardening** — `atris activate` and `atris` entry point detect Codex environments and write `AGENTS.md` so Codex sessions start with workspace context.

package/atris/skills/atris-feedback/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: atris-feedback
+description: Submit, list, resolve, close, or delete Atris customer feedback. Use when user types /feedback or asks to triage the feedback queue.
+version: 1.0.0
+tags:
+  - feedback
+  - customer
+  - admin
+---
+
+# Feedback
+
+One skill for everything: submit feedback, view the queue, resolve/close/delete items.
+
+## Parse the input
+
+- `/feedback` (no args) → show the queue
+- `/feedback <message>` → submit new feedback
+- `/feedback resolve <id> <resolution>` → mark as resolved, notify customer
+- `/feedback close <id>` → close as wontfix/duplicate
+- `/feedback delete <id>` → remove from queue
+
+## Preferred path: the Atris CLI
+
+The `atris` CLI wraps every feedback operation against the production API and
+handles auth from the user's login. Use it first — it's the canonical,
+audited path and works without needing AWS credentials.
+
+```bash
+atris feedback                              # list queue
+atris feedback "the calendar hangs"         # submit
+atris feedback resolve abc123 "fixed"       # mark resolved
+atris feedback close abc123                 # close as wontfix
+atris feedback delete abc123                # delete
+```
+
+IDs can be short (first 8 chars of the UUID) — the CLI resolves the prefix
+against the live list before acting.
+
+If `atris` is not on PATH, it lives at `~/arena/atris-cli/bin/atris.js`.
+
+## Fallback: direct API / DynamoDB
+
+Only use this path if the CLI is unavailable (stale install, broken login).
+
+### Setup
+
+```bash
+cd ~/arena/atrisos-backend && source venv/bin/activate
+```
+
+```python
+from dotenv import load_dotenv; load_dotenv('backend/.env')
+import boto3
+table = boto3.resource('dynamodb', region_name='us-east-1').Table('atris_feedback')
+```
+
+### Submit
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/feedback" \
+  -H "Content-Type: application/json" \
+  -H "X-Feedback-Key: $FEEDBACK_API_KEY" \
+  -d '{"message": "THE_MESSAGE", "source": "cli", "context": {"user_email": "GIT_EMAIL"}}'
+```
+
+Confirm: `Feedback submitted (id: abc123)`
+
+### Resolve
+
+```python
+table.update_item(
+    Key={'id': FULL_ID},
+    UpdateExpression='SET #s = :s, resolution = :r, resolved_at = :t',
+    ExpressionAttributeNames={'#s': 'status'},
+    ExpressionAttributeValues={':s': 'resolved', ':r': RESOLUTION, ':t': NOW},
+)
+```
+
+Print: `Resolved abc123: <resolution>`
+
+### Close
+
+Same as resolve but `status = 'closed'`, no resolution text needed.
+
+### Delete
+
+```python
+table.delete_item(Key={'id': FULL_ID})
+```
+
+Print: `Deleted abc123`
+
+### ID matching
+
+Users type short IDs (first 8 chars). Scan the table and match by prefix
+to find the full UUID.
+
+## Security
+
+- NEVER include API keys, tokens, or secrets in feedback messages
+- Server-side sanitization strips them anyway (double protection)
+- Max 2000 chars per message
+
+## Output
+
+Always print the result directly as text. Never leave it inside a tool
+call expansion.

package/bin/atris.js

@@ -247,7 +247,7 @@ function showHelp() {
   console.log('Optional helpers:');
   console.log('  brainstorm - Explore ideas conversationally before planning');
   console.log('  autopilot  - Guided loop that can clarify TODOs and run plan → do → review');
-  console.log('  visualize  - Legacy visualization helper (prefer "atris plan")');
+  console.log('  visualize  - Generate a Slack/deck-ready visual from a prompt');
   console.log('');
   console.log('Experiments:');
   console.log('  experiments init [slug]     - Prepare atris/experiments/ or scaffold a pack');
@@ -272,7 +272,7 @@ function showHelp() {
   console.log('  wake [business]    - Resume workspace (agents restart)');
   console.log('');
   console.log('Business:');
-  console.log('  business init <name>   - Create canonical business workspace (cloud + local)');
+  console.log('  business init <name>   - RECOMMENDED: create business environment (cloud + local)');
   console.log('  business onboard       - Onboard from sparse input (--name, --website, --contact)');
   console.log('  business add <slug>    - Connect a business');
   console.log('  business list          - Show connected businesses');
@@ -280,7 +280,7 @@ function showHelp() {
   console.log('  business team [slug]   - Show members, roles, and admin access');
   console.log('  business health <slug> - Health report (members, workspace, issues)');
   console.log('  business audit         - One-line health summary of all businesses');
-  console.log('  business create <name> - Create new business; add --workspace for canonical local scaffold');
+  console.log('  business create <name> - Cloud-only business record; add --workspace to also scaffold local');
   console.log('  business connect <svc> - Wire a skill/integration');
   console.log('  business notify <mode> - Set notification mode (digest/silent/push)');
   console.log('  business deploy <slug> - Push local business to cloud');
@@ -291,6 +291,7 @@ function showHelp() {
   console.log('');
   console.log('Cloud & agents:');
   console.log('  computer   - Talk directly to the AI computer (bash or agent exec)');
+  console.log('  receipt    - Save evidence from an agent run');
   console.log('  console    - Start/attach always-on coding console (tmux daemon)');
   console.log('  agent      - Select which Atris agent to use');
   console.log('  chat       - Chat with the selected Atris agent');
@@ -328,8 +329,11 @@ function showHelp() {
   console.log('  plugin info         - Preview what will be included');
   console.log('');
   console.log('Feedback:');
-  console.log('  feedback "msg"      - Submit feedback');
-  console.log('  feedback            - List your feedback');
+  console.log('  feedback "msg"             - Submit feedback');
+  console.log('  feedback                   - List feedback queue');
+  console.log('  feedback resolve <id> "<note>" - Mark resolved (admin)');
+  console.log('  feedback close <id>        - Close as wontfix (admin)');
+  console.log('  feedback delete <id>       - Delete feedback (admin)');
   console.log('');
   console.log('Other:');
   console.log('  version    - Show Atris version');
@@ -429,10 +433,10 @@ const { planAtris: planCmd, doAtris: doCmd, reviewAtris: reviewCmd } = require('
 // Check if this is a known command or natural language input
 const knownCommands = ['init', 'log', 'status', 'analytics', 'visualize', 'brainstorm', 'autopilot', 'run', 'plan', 'do', 'review', 'release',
                        'activate', '_activate', 'agent', 'chat', 'console', 'login', 'logout', 'whoami', 'switch', 'use', 'accounts', '_resolve', '_profile-email', '_switch-session', 'shell-init', 'update', 'upgrade', 'version', 'help', 'next', 'atris',
-                       'clean', 'verify', 'search', 'skill', 'member', 'app', 'learn', 'plugin', 'experiments', 'pull', 'push', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
+                       'clean', 'verify', 'search', 'skill', 'member', 'app', 'learn', 'plugin', 'experiments', 'receipt', 'proof', 'openclaw', 'pull', 'push', 'align', 'terminal', 'computer', 'diff', 'business', 'sync',
                        'ingest', 'query', 'lint', 'loop',
                        'gmail', 'calendar', 'twitter', 'slack', 'integrations', 'setup', 'clean-workspace', 'cw',
-                       'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'wiki', 'code-review', 'cr', 'soul', 'fleet'];
+                       'fork', 'browse', 'publish', 'sleep', 'wake', 'feedback', 'errors', 'wiki', 'code-review', 'cr', 'soul', 'fleet'];
 
 // Check if command is an atris.md spec file - triggers welcome visualization
 function isSpecFile(cmd) {
@@ -865,10 +869,9 @@ if (command === 'init') {
 } else if (command === 'shell-init') {
   require('../commands/auth').shellInit();
 } else if (command === 'visualize') {
-  console.log('ℹ️  "atris visualize" is a legacy helper. Visualization is now built into "atris plan".');
-  console.log('   Prefer: atris plan');
-  console.log('');
-  require('../commands/visualize').visualizeAtris();
+  require('../commands/visualize').visualizeAtris(process.argv.slice(3))
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else if (command === 'run') {
   const args = process.argv.slice(3);
   if (args.includes('--help') || args.includes('-h')) {
@@ -1157,6 +1160,10 @@ if (command === 'init') {
   const subcommand = process.argv[3];
   const args = process.argv.slice(4);
   require('../commands/experiments').experimentsCommand(subcommand, ...args);
+} else if (command === 'receipt' || command === 'proof' || command === 'openclaw') {
+  const subcommand = process.argv[3];
+  const args = process.argv.slice(4);
+  require('../commands/proof').proofCommand(subcommand, ...args);
 } else if (command === 'setup') {
   require('../commands/setup').setupAtris()
     .then(() => process.exit(0))
@@ -1185,6 +1192,10 @@ if (command === 'init') {
   require('../commands/feedback').feedbackCommand()
     .then(() => process.exit(0))
     .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
+} else if (command === 'errors') {
+  require('../commands/errors').errorsCommand()
+    .then(() => process.exit(0))
+    .catch((err) => { console.error(`\n✗ Error: ${err.message || err}`); process.exit(1); });
 } else {
   console.log(`Unknown command: ${command}`);
   console.log('Run "atris help" to see available commands');

package/commands/business.js

@@ -13,6 +13,20 @@ function getBusinessConfigPath() {
   return path.join(dir, 'businesses.json');
 }
 
+function slugify(name) {
+  return String(name || '')
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function isHelpToken(arg) {
+  return arg === '--help' || arg === '-h' || arg === 'help' || arg === '-?';
+}
+
 function loadBusinesses() {
   const p = getBusinessConfigPath();
   if (!fs.existsSync(p)) return {};
@@ -774,7 +788,45 @@ function detectBusinessSlug(explicitSlug) {
   }
 }
 
+async function findExistingBusinessBySlug(slug, token) {
+  if (!slug) return null;
+
+  // Local cache first — no network round-trip needed.
+  const local = loadBusinesses();
+  if (local[slug]) {
+    return { id: local[slug].business_id, name: local[slug].name, slug, source: 'local' };
+  }
+  for (const v of Object.values(local)) {
+    if (v && v.slug === slug) {
+      return { id: v.business_id, name: v.name, slug, source: 'local' };
+    }
+  }
+
+  if (!token) return null;
+
+  // Cloud lookup — covers businesses the user is a member of but hasn't added.
+  const direct = await apiRequestJson(`/business/by-slug/${encodeURIComponent(slug)}`, {
+    method: 'GET',
+    token,
+  });
+  if (direct.ok && direct.data && direct.data.id) {
+    return { id: direct.data.id, name: direct.data.name, slug: direct.data.slug || slug, source: 'cloud' };
+  }
+
+  const list = await apiRequestJson('/business/', { method: 'GET', token });
+  if (list.ok && Array.isArray(list.data)) {
+    const match = list.data.find(b => b && b.slug === slug);
+    if (match) return { id: match.id, name: match.name, slug: match.slug, source: 'cloud' };
+  }
+
+  return null;
+}
+
 async function addBusiness(slug) {
+  if (!slug || isHelpToken(slug)) {
+    console.error('Usage: atris business add <slug>');
+    process.exit(1);
+  }
   if (!slug) {
     console.error('Usage: atris business add <slug>');
     process.exit(1);
@@ -1008,7 +1060,7 @@ function listBusinessesLocal(opts = {}) {
 }
 
 async function removeBusiness(slug) {
-  if (!slug) {
+  if (!slug || isHelpToken(slug)) {
     console.error('Usage: atris business remove <slug>');
     process.exit(1);
   }
@@ -1262,8 +1314,11 @@ async function businessAudit() {
 }
 
 async function createBusinessInternal(name, flags = [], mode = 'auto') {
-  if (!name) {
+  if (!name || isHelpToken(name) || String(name).startsWith('-')) {
     console.error('Usage: atris business create <name> [--description "..."] [--workspace] [--here|--root <dir>]');
+    if (name && String(name).startsWith('-') && !isHelpToken(name)) {
+      console.error(`\n  Refusing to create a business named "${name}" — looks like a flag, not a name.`);
+    }
     process.exit(1);
   }
 
@@ -1275,6 +1330,29 @@ async function createBusinessInternal(name, flags = [], mode = 'auto') {
 
   const options = parseCreateBusinessFlags(flags);
   const description = options.description;
+  const force = flags.includes('--force') || flags.includes('--allow-duplicate');
+
+  // Pre-flight: refuse to create a duplicate by slug. The backend will silently
+  // suffix `-1`, `-2`, etc., which produces ghost businesses when users actually
+  // wanted to attach to an existing one. Guide them to `atris pull` instead.
+  if (!force) {
+    const desiredSlug = slugify(name);
+    if (desiredSlug) {
+      const existing = await findExistingBusinessBySlug(desiredSlug, creds.token);
+      if (existing) {
+        console.error(`\nA business with slug "${desiredSlug}" already exists.`);
+        console.error(`  Name: ${existing.name || desiredSlug}`);
+        if (existing.id) console.error(`  ID:   ${existing.id}`);
+        console.error('');
+        console.error('To set up a local workspace for it, run:');
+        console.error(`  atris pull ${desiredSlug}                       # into ./${desiredSlug}`);
+        console.error(`  atris pull ${desiredSlug} --into <path>         # into a custom path`);
+        console.error('');
+        console.error(`To create a NEW business anyway (will be slugged "${desiredSlug}-1"), pass --force.`);
+        process.exit(1);
+      }
+    }
+  }
 
   console.log(`Creating business: ${name}...`);
 
@@ -1832,12 +1910,52 @@ async function quickstart() {
      (get 1 email/day instead of every notification)
 
   Templates: saas, agency, ecommerce, content, restaurant
+
+  Rule of thumb:
+     atris business init "<name>"    = cloud + local business computer workspace
+     atris business create "<name>"  = cloud-only unless you pass --workspace
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 `);
 }
 
 
+function printBusinessHelp() {
+  console.log('Usage: atris business <command> [args]');
+  console.log('');
+  console.log('  quickstart           ← Start here! 3-command guide');
+  console.log('');
+  console.log('  init <name>          RECOMMENDED: create a business environment (cloud + local)');
+  console.log('  workspace <name>     Alias for init');
+  console.log('  create <name>        Cloud-only business record; add --workspace to also scaffold local');
+  console.log('  add <slug>           Register an existing cloud business');
+  console.log('  list                 Show registered businesses');
+  console.log('  team [slug]          Show members, roles, and admin access');
+  console.log('  status <slug>        Quick status check');
+  console.log('  health [slug]        Full health dashboard');
+  console.log('  audit                Audit all businesses');
+  console.log('  connect <service>    Connect a skill/integration');
+  console.log('  notify <mode>        Set notification mode (digest/silent/push)');
+  console.log('  deploy <slug>        Push local business to cloud');
+  console.log('  onboard              Seed brief, person, first loop, safe next action, and one-pager from sparse input');
+  console.log('  record <report>      Append recap state into events, episodes, and scorecards');
+  console.log('  remove <slug>        Unregister locally');
+  console.log('');
+  console.log('  Already-attached business? Run `atris pull <slug>` to scaffold a local workspace.');
+}
+
 async function businessCommand(subcommand, ...args) {
+  // Help intercept — without this, `atris business init --help` would treat
+  // `--help` as a business name and create one. Same for any subcommand that
+  // takes a positional name/slug.
+  if (!subcommand || isHelpToken(subcommand)) {
+    printBusinessHelp();
+    return;
+  }
+  if (args.length > 0 && isHelpToken(args[0])) {
+    printBusinessHelp();
+    return;
+  }
+
   switch (subcommand) {
     case 'add':
       await addBusiness(args[0]);
@@ -1907,25 +2025,10 @@ async function businessCommand(subcommand, ...args) {
       await quickstart();
       break;
     default:
-      console.log('Usage: atris business <command> [args]');
-      console.log('');
-      console.log('  quickstart           ← Start here! 3-command guide');
-      console.log('');
-      console.log('  init <name>          Create a business environment (cloud + local)');
-      console.log('  workspace <name>     Alias for init');
-      console.log('  create <name>        Create the cloud business; add --workspace for a local business environment');
-      console.log('  add <slug>           Register an existing cloud business');
-      console.log('  list                 Show registered businesses');
-      console.log('  team [slug]          Show members, roles, and admin access');
-      console.log('  status <slug>        Quick status check');
-      console.log('  health [slug]        Full health dashboard');
-      console.log('  audit                Audit all businesses');
-      console.log('  connect <service>    Connect a skill/integration');
-      console.log('  notify <mode>        Set notification mode (digest/silent/push)');
-      console.log('  deploy <slug>        Push local business to cloud');
-      console.log('  onboard              Seed brief, person, first loop, safe next action, and one-pager from sparse input');
-      console.log('  record <report>      Append recap state into events, episodes, and scorecards');
-      console.log('  remove <slug>        Unregister locally');
+      console.error(`Unknown subcommand: ${subcommand}`);
+      console.error('');
+      printBusinessHelp();
+      process.exitCode = 1;
   }
 }