atris 3.15.23 → 3.15.30

package/commands/aeo.js

@@ -1,24 +1,98 @@
 /**
  * atris aeo — AI Engine Optimization commands
  *
- *   atris aeo init                          # create entity-graph skeleton in workspace
- *   atris aeo draft "<topic>" [opts]        # generate citation-optimized article (credit-metered)
+ * Backend-routed (require EC2):
+ *   atris aeo init                          # create entity-graph skeleton
+ *   atris aeo draft "<topic>" [opts]        # generate citation-optimized article
  *
- * Hits the backend endpoints registered under:
- *   POST /api/business/{id}/workspaces/{ws}/aeo/init
- *   POST /api/business/{id}/workspaces/{ws}/aeo/draft
+ * Local-read against ~/arena/atrisos-backend/atris/features/aeo/proof/:
+ *   atris aeo log [--engine X] [--limit N]  # citation attempt log
+ *   atris aeo status                        # engine + proof + buyer summary
+ *   atris aeo packet <slug>                 # buyer packet for a surface
+ *   atris aeo proofs [--filter X]           # list proof receipt categories
  *
- * Business resolution mirrors `atris terminal`: explicit --workspace slug,
- * else cwd .atris/business.json. The endpoint itself takes care of running
- * Claude Sonnet 4.6 with the 10 AEO rules and writing to /workspace/atris/aeo/drafts/.
+ * Shell out to atrisos-backend/scripts/aeo_*.py:
+ *   atris aeo discover <source> [...]       # discovery audit
+ *   atris aeo audit <source> [...]          # agent-usability audit
+ *
+ * Backend root resolution: $ATRIS_BACKEND_ROOT or ~/arena/atrisos-backend.
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { loadCredentials } = require('../utils/auth');
 const { apiRequestJson } = require('../utils/api');
 const { loadBusinesses, saveBusinesses } = require('./business');
 
+function resolveBackendRoot() {
+  const candidates = [
+    process.env.ATRIS_BACKEND_ROOT,
+    path.join(os.homedir(), 'arena', 'atrisos-backend'),
+  ].filter(Boolean);
+  for (const root of candidates) {
+    if (fs.existsSync(path.join(root, 'atris', 'features', 'aeo'))) return root;
+  }
+  return null;
+}
+
+function requireBackendRoot() {
+  const root = resolveBackendRoot();
+  if (!root) {
+    console.error('Cannot find atrisos-backend. Set $ATRIS_BACKEND_ROOT or clone to ~/arena/atrisos-backend.');
+    process.exit(1);
+  }
+  return root;
+}
+
+function readJsonSafe(p) {
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (err) {
+    console.error(`  warning: malformed JSON at ${p} (${err.message})`);
+    return null;
+  }
+}
+
+function pad(s, n) { s = String(s); return s.length >= n ? s.slice(0, n) : s + ' '.repeat(n - s.length); }
+
+function assertNoExtras(sub, args, allowedFlags) {
+  const allowed = new Set(allowedFlags);
+  const unknownFlags = args.filter((a) => a.startsWith('--') && !allowed.has(a));
+  const positional = args.filter((a) => !a.startsWith('--'));
+  if (unknownFlags.length) {
+    console.error(`Unknown flag for aeo ${sub}: ${unknownFlags.join(' ')}. Supported: ${[...allowed].join(' ') || '(none)'}`);
+    process.exit(1);
+  }
+  if (positional.length) {
+    console.error(`Unexpected argument for aeo ${sub}: ${positional.join(' ')}`);
+    process.exit(1);
+  }
+}
+
+function readArg(args, ...keys) {
+  for (const k of keys) {
+    const eqIdx = args.findIndex((a) => a.startsWith(`${k}=`));
+    if (eqIdx !== -1) {
+      const v = args[eqIdx].slice(k.length + 1);
+      args.splice(eqIdx, 1);
+      return v;
+    }
+    const i = args.findIndex((a) => a === k);
+    if (i === -1) continue;
+    const v = args[i + 1];
+    if (v === undefined || v.startsWith('--')) {
+      console.error(`Flag ${k} requires a value.`);
+      process.exit(1);
+    }
+    args.splice(i, 2);
+    return v;
+  }
+  return null;
+}
+
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
 async function ensureAwake(token, businessId, maxWaitSec = 90) {
@@ -83,13 +157,25 @@ function pickSlug(args) {
 
 function printHelp() {
   console.log('Usage:');
-  console.log('  atris aeo init [--workspace <slug>]');
-  console.log('  atris aeo draft "<topic>" [--workspace <slug>] [--queries q1,q2] [--slug X] [--url URL]');
+  console.log('  Backend / EC2:');
+  console.log('    atris aeo init   [--workspace <slug>]');
+  console.log('    atris aeo draft  "<topic>" [--workspace <slug>] [--queries q1,q2] [--slug X] [--url URL]');
+  console.log('');
+  console.log('  Local read (atris/features/aeo/proof/):');
+  console.log('    atris aeo log    [--engine X] [--limit N] [--json]');
+  console.log('    atris aeo status [--json]');
+  console.log('    atris aeo packet <slug> [--json]');
+  console.log('    atris aeo proofs [--filter X]');
+  console.log('');
+  console.log('  Script wrappers (scripts/aeo_*.py):');
+  console.log('    atris aeo discover <source> [--question Q ...] [--canonical-url URL] [--out-dir DIR]');
+  console.log('    atris aeo audit    <source> [--baseline B] [--canonical-url URL] [--out-dir DIR]');
   console.log('');
   console.log('Examples:');
-  console.log('  atris aeo init');
-  console.log('  atris aeo draft "what is example-co" --queries "what is example-co,best freight platform"');
-  console.log('  atris aeo draft "how does atris work" --workspace doordash --slug atris-overview');
+  console.log('  atris aeo log --engine perplexity --limit 5');
+  console.log('  atris aeo packet pallet');
+  console.log('  atris aeo status');
+  console.log('  atris aeo discover https://atris.ai/aeo --canonical-url https://atris.ai/aeo');
 }
 
 async function aeoInit(args) {
@@ -183,12 +269,290 @@ async function aeoDraft(args) {
   if (data.hint) console.log(`  hint:           ${data.hint}`);
 }
 
+// ---------- LOCAL READ SUBCOMMANDS ----------
+
+function loadCitationAttempts(root) {
+  const dir = path.join(root, 'atris', 'features', 'aeo', 'proof', 'live-citation-attempts');
+  if (!fs.existsSync(dir)) return [];
+  const rows = [];
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    const data = readJsonSafe(path.join(dir, file));
+    if (!data || !Array.isArray(data.attempts)) continue;
+    for (const attempt of data.attempts) {
+      if (!attempt || typeof attempt !== 'object') continue;
+      const cited = attempt.answer_cites_target_url === true;
+      const mentioned = attempt.answer_mentions_target_entity === true;
+      let status;
+      if (cited) status = 'verified';
+      else if (mentioned) status = 'pending';
+      else status = 'failed';
+      const str = (v) => (typeof v === 'string' ? v : '');
+      const arr = (v) => (Array.isArray(v) ? v : []);
+      rows.push({
+        file,
+        attempted_at: str(data.attempted_at),
+        engine: str(data.engine),
+        prompt_id: str(attempt.prompt_id),
+        prompt: str(attempt.exact_prompt),
+        target_entity: str(data.target_entity),
+        target_urls: arr(data.target_url_candidates),
+        answer_evidence_uri: str(attempt.answer_evidence_uri),
+        status,
+        competitors: arr(attempt.observed_competitor_or_alternative_entities),
+      });
+    }
+  }
+  rows.sort((a, b) => (b.attempted_at || '').localeCompare(a.attempted_at || ''));
+  return rows;
+}
+
+async function aeoLog(args) {
+  const engine = readArg(args, '--engine', '-e');
+  const limitRaw = readArg(args, '--limit', '-n');
+  assertNoExtras('log', args, ['--json']);
+  const wantJson = args.includes('--json');
+  let limit = 20;
+  if (limitRaw != null) {
+    const trimmed = String(limitRaw).trim();
+    const parsed = parseInt(trimmed, 10);
+    if (!/^[+-]?\d+$/.test(trimmed) || !Number.isFinite(parsed) || parsed < 1) {
+      console.error(`Invalid --limit value: "${limitRaw}". Expected a positive integer.`);
+      process.exit(1);
+    }
+    limit = parsed;
+  }
+  const root = requireBackendRoot();
+  let rows = loadCitationAttempts(root);
+  if (engine) rows = rows.filter((r) => r.engine.toLowerCase() === engine.toLowerCase());
+  rows = rows.slice(0, limit);
+
+  if (wantJson) {
+    console.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+
+  if (!rows.length) {
+    console.log('No citation attempts found.');
+    return;
+  }
+
+  const counts = rows.reduce((acc, r) => { acc[r.status] = (acc[r.status] || 0) + 1; return acc; }, {});
+  console.log(`AEO citation log (${rows.length} attempt${rows.length === 1 ? '' : 's'})`);
+  console.log(`  ${Object.entries(counts).map(([k, v]) => `${k}=${v}`).join('  ')}`);
+  console.log('');
+  console.log(`  ${pad('ts', 22)}${pad('engine', 12)}${pad('prompt_id', 26)}${pad('status', 10)}`);
+  console.log(`  ${'-'.repeat(70)}`);
+  for (const r of rows) {
+    console.log(`  ${pad(r.attempted_at.slice(0, 19), 22)}${pad(r.engine, 12)}${pad(r.prompt_id, 26)}${pad(r.status, 10)}`);
+  }
+}
+
+async function aeoStatus(args) {
+  assertNoExtras('status', args, ['--json']);
+  const wantJson = args.includes('--json');
+  const root = requireBackendRoot();
+  const proofRoot = path.join(root, 'atris', 'features', 'aeo', 'proof');
+
+  const attempts = loadCitationAttempts(root);
+  const enginesSeen = new Set(attempts.map((a) => a.engine).filter(Boolean));
+  const verified = attempts.filter((a) => a.status === 'verified').length;
+  const pending = attempts.filter((a) => a.status === 'pending').length;
+  const failed = attempts.filter((a) => a.status === 'failed').length;
+
+  const packets = [];
+  if (fs.existsSync(proofRoot)) {
+    for (const entry of fs.readdirSync(proofRoot)) {
+      if (!entry.endsWith('-buyer-packet')) continue;
+      const p = path.join(proofRoot, entry, 'packet.json');
+      const data = readJsonSafe(p);
+      if (!data) continue;
+      packets.push({
+        slug: entry.replace(/-buyer-packet$/, ''),
+        surface: data.surface || entry,
+        target_url: data.target_url || '',
+        baseline: data?.agent_usability?.baseline_score ?? null,
+        proposed: data?.agent_usability?.proposed_score ?? null,
+        claim_status: data.claim_status || '',
+      });
+    }
+  }
+
+  const operator = readJsonSafe(path.join(proofRoot, 'live-citation-operator', 'live-citation-operator.json'));
+
+  const proofDirs = fs.existsSync(proofRoot)
+    ? fs.readdirSync(proofRoot).filter((e) => fs.statSync(path.join(proofRoot, e)).isDirectory()).length
+    : 0;
+
+  if (wantJson) {
+    console.log(JSON.stringify({
+      backend_root: root,
+      proof_dirs: proofDirs,
+      citation: { total: attempts.length, verified, pending, failed, engines: [...enginesSeen] },
+      packets,
+      operator_status: operator?.status || null,
+      operator_blocker: operator?.current_blocker || null,
+    }, null, 2));
+    return;
+  }
+
+  console.log('Atris AEO status');
+  console.log(`  backend root:      ${root}`);
+  console.log(`  proof receipts:    ${proofDirs} categories`);
+  console.log('');
+  console.log('Live citations');
+  console.log(`  attempts:          ${attempts.length}`);
+  console.log(`  verified:          ${verified}`);
+  console.log(`  pending:           ${pending}`);
+  console.log(`  failed:            ${failed}`);
+  console.log(`  engines observed:  ${[...enginesSeen].join(', ') || '(none)'}`);
+  if (operator) {
+    console.log(`  operator state:    ${operator.status || '?'} (blocker: ${operator.current_blocker || 'none'})`);
+  }
+  console.log('');
+  console.log(`Buyer packets (${packets.length})`);
+  for (const p of packets) {
+    const delta = p.baseline != null && p.proposed != null ? `${p.baseline} → ${p.proposed}` : '?';
+    console.log(`  ${pad(p.slug, 16)} ${pad(p.target_url || p.surface, 36)} ${pad(delta, 12)} ${p.claim_status}`);
+  }
+}
+
+async function aeoPacket(args) {
+  const known = new Set(['--json']);
+  const positional = [];
+  for (const a of args) {
+    if (a.startsWith('--')) {
+      if (!known.has(a)) {
+        console.error(`Unknown flag: ${a}. Supported: --json`);
+        process.exit(1);
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length === 0) {
+    console.error('Missing slug. Usage: atris aeo packet <slug>');
+    process.exit(1);
+  }
+  if (positional.length > 1) {
+    console.error(`Too many arguments: ${positional.join(' ')}. Expected one slug.`);
+    process.exit(1);
+  }
+  const slug = positional[0];
+  const wantJson = args.includes('--json');
+  const root = requireBackendRoot();
+  const file = path.join(root, 'atris', 'features', 'aeo', 'proof', `${slug}-buyer-packet`, 'packet.json');
+  const data = readJsonSafe(file);
+  if (!data) {
+    console.error(`Packet not found: ${file}`);
+    process.exit(1);
+  }
+
+  if (wantJson) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+
+  const u = (data && typeof data.agent_usability === 'object' && data.agent_usability) || {};
+  const onlyObjects = (v) => (Array.isArray(v) ? v.filter((x) => x && typeof x === 'object') : []);
+  const friction = onlyObjects(u.baseline_friction_points);
+  const fixes = onlyObjects(u.fix_backlog);
+  console.log(`AEO buyer packet — ${slug}`);
+  console.log(`  surface:        ${data.surface || ''}`);
+  console.log(`  target url:     ${data.target_url || ''}`);
+  console.log(`  claim status:   ${data.claim_status || ''}`);
+  console.log(`  positioning:    ${u.positioning || ''}`);
+  console.log('');
+  console.log('Agent usability scores');
+  console.log(`  baseline:       ${u.baseline_score ?? '?'}`);
+  console.log(`  proposed:       ${u.proposed_score ?? '?'}`);
+  console.log(`  delta:          ${u.score_delta ?? '?'}`);
+  console.log(`  verified:       ${u.movement_verified ? 'yes' : 'no'}`);
+  console.log('');
+  console.log(`Baseline friction (${friction.length})`);
+  for (const f of friction) {
+    console.log(`  [${f.severity || '?'}] ${f.stage || '?'}: ${f.missing_artifact || f.id || ''}`);
+  }
+  console.log('');
+  console.log(`Fix backlog (${fixes.length})`);
+  for (const f of fixes) {
+    console.log(`  #${f.priority ?? '?'} ${f.stage || '?'}: ${f.action || ''}`);
+  }
+}
+
+async function aeoProofs(args) {
+  const filter = readArg(args, '--filter', '-f');
+  assertNoExtras('proofs', args, []);
+  const root = requireBackendRoot();
+  const proofRoot = path.join(root, 'atris', 'features', 'aeo', 'proof');
+  if (!fs.existsSync(proofRoot)) {
+    console.error(`Proof root not found: ${proofRoot}`);
+    process.exit(1);
+  }
+  const needle = filter ? filter.toLowerCase() : null;
+  const entries = fs.readdirSync(proofRoot)
+    .filter((e) => fs.statSync(path.join(proofRoot, e)).isDirectory())
+    .filter((e) => !needle || e.toLowerCase().includes(needle))
+    .sort();
+  console.log(`AEO proof receipts at ${path.relative(process.cwd(), proofRoot)}`);
+  console.log('');
+  for (const e of entries) {
+    const files = fs.readdirSync(path.join(proofRoot, e)).filter((f) => f.endsWith('.json'));
+    console.log(`  ${pad(e, 44)} ${files.length} file${files.length === 1 ? '' : 's'}`);
+  }
+}
+
+// ---------- SCRIPT WRAPPERS ----------
+
+function runBackendScript(scriptName, args) {
+  const root = requireBackendRoot();
+  const script = path.join(root, 'scripts', scriptName);
+  if (!fs.existsSync(script)) {
+    console.error(`Script not found: ${script}`);
+    process.exit(1);
+  }
+  const py = process.env.ATRIS_PYTHON || 'python3';
+  const result = spawnSync(py, [script, ...args], { cwd: root, stdio: 'inherit' });
+  if (result.error) {
+    console.error(`Failed to spawn ${py}: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) {
+    const signum = os.constants?.signals?.[result.signal] ?? 0;
+    console.error(`${scriptName} terminated by signal ${result.signal}`);
+    process.exit(128 + signum);
+  }
+  process.exit(result.status ?? 1);
+}
+
+async function aeoDiscover(args) {
+  if (!args.length || args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: atris aeo discover <source> [--question Q]... [--canonical-url URL] [--out-dir DIR] [--json]');
+    return;
+  }
+  runBackendScript('aeo_discovery_audit.py', args);
+}
+
+async function aeoAudit(args) {
+  if (!args.length || args[0] === '--help' || args[0] === '-h') {
+    console.log('Usage: atris aeo audit <source> [--baseline B] [--canonical-url URL] [--out-dir DIR] [--task T]');
+    return;
+  }
+  runBackendScript('aeo_agent_usability_audit.py', args);
+}
+
 async function run(args = []) {
   const sub = args[0];
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h') return printHelp();
   const rest = args.slice(1);
   if (sub === 'init') return aeoInit(rest);
   if (sub === 'draft') return aeoDraft(rest);
+  if (sub === 'log') return aeoLog(rest);
+  if (sub === 'status') return aeoStatus(rest);
+  if (sub === 'packet') return aeoPacket(rest);
+  if (sub === 'proofs') return aeoProofs(rest);
+  if (sub === 'discover') return aeoDiscover(rest);
+  if (sub === 'audit') return aeoAudit(rest);
   console.error(`Unknown aeo subcommand: ${sub}`);
   printHelp();
   process.exit(1);

package/commands/gm.js

@@ -4,6 +4,8 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+const AGENTXP_LEADERBOARD_URL = 'https://api.atris.ai/api/agentxp/leaderboard';
+
 const ROLE_PLAYERS_TO_IGNORE = new Set([
   'game-manager',
   'navigator',
@@ -26,7 +28,7 @@ function showHelp() {
   console.log('');
   console.log('Options:');
   console.log('  --manager <id>    Manager id. Defaults to game-manager when present.');
-  console.log('  --as <id>         Alias for --manager.');
+  console.log('  --as <id>         Alias for --player.');
   console.log('  --player <id>     Preferred player when seeding a first local mission.');
   console.log('  --workspace <p>   Read missions from another Atris workspace.');
   console.log('  --no-seed         Do not create a starter player mission.');
@@ -102,7 +104,7 @@ function teamMembers(workspaceRoot) {
 }
 
 function inferManager(workspaceRoot, args = []) {
-  const explicit = flag(args, '--manager') || flag(args, '--as') || positional(args)[0];
+  const explicit = flag(args, '--manager') || positional(args)[0];
   if (explicit) return { manager: slugify(explicit), source: 'flag' };
 
   for (const value of [process.env.ATRIS_GM, process.env.ATRIS_MANAGER, process.env.ATRIS_AGENT_ID]) {
@@ -160,7 +162,7 @@ function starterMissionPrompt(player) {
 }
 
 function pickSeedPlayer(workspaceRoot, tasks, args = []) {
-  const explicit = flag(args, '--player') || flag(args, '--user');
+  const explicit = flag(args, '--player') || flag(args, '--user') || flag(args, '--as');
   if (explicit) return slugify(explicit);
 
   const fromTasks = playersFromTasks(tasks);
@@ -261,19 +263,29 @@ function compactTask(task) {
   };
 }
 
-function nextCommands({ seeded, reviewQueue, missions, players }) {
+function globalSyncCommands(player) {
+  return [
+    'atris login',
+    `atris xp sync --local --as ${player}`,
+  ];
+}
+
+function nextCommands({ seeded, reviewQueue, missions, players, manager }) {
   if (reviewQueue.length) {
-    const ref = reviewQueue[0].ref;
+    const task = reviewQueue[0];
+    const ref = task.ref;
+    const player = task.assigned_to || task.claimed_by || players[0]?.player || 'player';
     return [
       `atris task show ${ref}`,
-      `atris task accept ${ref} --proof "<human review>"`,
-      `atris task revise ${ref} --note "<what must change>"`,
+      `atris task accept ${ref} --as ${player} --proof "<human review>"`,
+      `atris task revise ${ref} --as ${player} --note "<what must change>"`,
+      ...globalSyncCommands(player),
     ];
   }
   if (missions.length) {
     const mission = missions[0];
     const player = mission.assigned_to || mission.claimed_by || players[0]?.player || 'player';
-    if (mission.status === 'open') return [`atris task claim ${mission.ref} --as ${player}`];
+    if (mission.status === 'open') return [`atris task claim ${mission.ref} --as ${manager || 'game-manager'}`];
     return [`atris play --as ${player}`];
   }
   if (seeded) return [`atris play --as ${seeded.assigned_to || 'player'}`];
@@ -297,7 +309,7 @@ function gmState(args = []) {
   const reviewQueue = missions.filter(task => task.status === 'review');
   const players = groupPlayers(tasks, workspaceRoot);
   const seeded = compactTask(starter.seeded);
-  const commands = nextCommands({ seeded, reviewQueue, missions, players });
+  const commands = nextCommands({ seeded, reviewQueue, missions, players, manager: detected.manager });
 
   return {
     schema: 'atris.agentxp_gm_mode.v1',
@@ -318,6 +330,8 @@ function gmState(args = []) {
     review_queue: reviewQueue,
     next_commands: commands,
     xp_rule: 'GM can route missions and review proof, but AgentXP still lands only after human accept.',
+    global_sync_rule: 'Run atris login once before syncing to the hosted AgentXP leaderboard.',
+    leaderboard_url: AGENTXP_LEADERBOARD_URL,
   };
 }
 
@@ -351,6 +365,8 @@ function render(state) {
 
   console.log('');
   console.log('XP rule: no proof, no AgentXP; accept/revise stays human-gated.');
+  console.log('Global sync: run atris login once before hosted leaderboard sync.');
+  console.log(`Leaderboard: ${state.leaderboard_url}`);
   console.log('');
   console.log('Next commands:');
   for (const command of state.next_commands) console.log(`- ${command}`);

package/commands/play.js

@@ -6,6 +6,8 @@ const fs = require('fs');
 const { spawnSync } = require('child_process');
 const { getSessionProfile, loadCredentials } = require('../utils/auth');
 
+const AGENTXP_LEADERBOARD_URL = 'https://api.atris.ai/api/agentxp/leaderboard';
+
 function showHelp() {
   console.log('');
   console.log('Usage: atris play [--as <player>] [--workspace <path>] [--json]');
@@ -252,10 +254,17 @@ function starterMissionPrompt(player) {
   ].join(' ');
 }
 
+function globalSyncCommands(player) {
+  return [
+    'atris login',
+    `atris xp sync --local --as ${player}`,
+  ];
+}
+
 function ensureStarterMission(taskDb, db, workspaceRoot, player, tasks, args = []) {
   if (hasFlag(args, '--no-seed')) return { tasks, seeded: null };
   if (selectMission(tasks, player)) return { tasks, seeded: null };
-  if (!fs.existsSync(path.join(workspaceRoot, 'atris'))) return { tasks, seeded: null };
+  fs.mkdirSync(path.join(workspaceRoot, 'atris'), { recursive: true });
 
   const result = taskDb.addTask(db, {
     title: starterMissionTitle(),
@@ -282,7 +291,21 @@ function ensureStarterMission(taskDb, db, workspaceRoot, player, tasks, args = [
   return { tasks: refreshed, seeded };
 }
 
+function playWorkspaceRoot(taskDb, workspaceArg) {
+  let requested = path.resolve(workspaceArg || process.cwd());
+  try { requested = fs.realpathSync(requested); } catch {}
+  if (
+    fs.existsSync(path.join(requested, '.git'))
+    || fs.existsSync(path.join(requested, 'atris'))
+    || fs.existsSync(path.join(requested, '.atris'))
+  ) {
+    return taskDb.workspaceRoot(requested);
+  }
+  return requested;
+}
+
 function nextCommands(task, player) {
+  const helper = 'game-manager';
   if (!task) {
     return [
       `atris task delegate "AgentXP first rep: one proof-backed mission" --to ${player} --tag agent-xp`,
@@ -293,40 +316,45 @@ function nextCommands(task, player) {
   const ref = taskRef(task);
   if (task.status === 'open') {
     return [
-      `atris task claim ${ref} --as ${player}`,
-      `atris task ready ${ref} --proof "<artifact path + verifier result>"`,
-      `atris task accept ${ref} --proof "<human review>"`,
+      `atris task claim ${ref} --as ${helper}`,
+      `atris task ready ${ref} --as ${helper} --proof "<artifact path + verifier result>"`,
+      `atris task accept ${ref} --as ${player} --proof "<human review>"`,
       'atris xp card --local',
+      ...globalSyncCommands(player),
     ];
   }
 
   if (task.status === 'claimed') {
+    const actor = task.claimed_by || helper;
     return [
-      `atris task ready ${ref} --proof "<artifact path + verifier result>"`,
-      `atris task accept ${ref} --proof "<human review>"`,
+      `atris task ready ${ref} --as ${actor} --proof "<artifact path + verifier result>"`,
+      `atris task accept ${ref} --as ${player} --proof "<human review>"`,
       'atris xp card --local',
+      ...globalSyncCommands(player),
     ];
   }
 
   if (task.status === 'review') {
     return [
       `atris task show ${ref}`,
-      `atris task accept ${ref} --proof "<human review>"`,
-      `atris task revise ${ref} --note "<what must change>"`,
+      `atris task accept ${ref} --as ${player} --proof "<human review>"`,
+      `atris task revise ${ref} --as ${player} --note "<what must change>"`,
       'atris xp card --local',
+      ...globalSyncCommands(player),
     ];
   }
 
   return [
     `atris task show ${ref}`,
     'atris xp card --local',
+    ...globalSyncCommands(player),
   ];
 }
 
 function modeState(args = []) {
   const taskDb = require('../lib/task-db');
   const workspaceArg = flag(args, '--workspace') || flag(args, '--root') || process.cwd();
-  const workspaceRoot = taskDb.workspaceRoot(path.resolve(workspaceArg));
+  const workspaceRoot = playWorkspaceRoot(taskDb, workspaceArg);
   const db = taskDb.open();
   const rows = taskDb.listTasks(db, {
     workspaceRoot,
@@ -367,6 +395,8 @@ function modeState(args = []) {
       prompt: latestMessage(events),
     } : null,
     xp_rule: 'AgentXP lands only after proof is ready and a human accepts the task.',
+    global_sync_rule: 'Run atris login once before syncing to the hosted AgentXP leaderboard.',
+    leaderboard_url: AGENTXP_LEADERBOARD_URL,
     next_commands: commandList,
   };
 }
@@ -399,6 +429,8 @@ function render(state) {
   console.log('');
   console.log('Win condition: real artifact + verifier + human accept.');
   console.log('XP rule: no proof, no AgentXP; accept/revise stays human-gated.');
+  console.log('Global sync: run atris login once before hosted leaderboard sync.');
+  console.log(`Leaderboard: ${state.leaderboard_url}`);
   console.log('');
   console.log('Next commands:');
   for (const command of state.next_commands) console.log(`- ${command}`);

package/commands/sync.js

@@ -48,6 +48,10 @@ function _substituteParams(content, params) {
     .replace(/\{\{workspace_template\}\}/g, params.workspace_template || 'business');
 }
 
+function _templateTargetRelPath(relPath) {
+  return relPath === 'persona.md' ? 'PERSONA.md' : relPath;
+}
+
 /**
  * Sync the canonical skill set from atris-cli/atris/skills/* into a
  * workspace's atris/skills/* (plus ensure .claude/skills/ symlinks).
@@ -212,14 +216,15 @@ function syncWorkspaceTemplate(targetRoot, bizMeta, options = {}) {
   const addedList = [], updatedList = [], preservedList = [];
 
   for (const relPath of templateFiles) {
+    const targetRelPath = _templateTargetRelPath(relPath);
     const templatePath = path.join(template.dir, relPath);
-    const targetPath = path.join(targetAtrisDir, relPath);
+    const targetPath = path.join(targetAtrisDir, targetRelPath);
     let templateContent;
     try { templateContent = fs.readFileSync(templatePath, 'utf-8'); } catch { continue; }
     const finalContent = _substituteParams(templateContent, params);
 
     if (!fs.existsSync(targetPath)) {
-      addedList.push(relPath); added++;
+      addedList.push(targetRelPath); added++;
       if (!dryRun) {
         fs.mkdirSync(path.dirname(targetPath), { recursive: true });
         fs.writeFileSync(targetPath, finalContent);
@@ -229,10 +234,10 @@ function syncWorkspaceTemplate(targetRoot, bizMeta, options = {}) {
       if (existing === finalContent) {
         skipped++;
       } else if (force) {
-        updatedList.push(relPath); updated++;
+        updatedList.push(targetRelPath); updated++;
         if (!dryRun) fs.writeFileSync(targetPath, finalContent);
       } else {
-        preservedList.push(relPath); preserved++;
+        preservedList.push(targetRelPath); preserved++;
       }
     }
   }