--- name: admin description: Manage Brain API keys from the admin panel help_jtbd: "Inspect plugin internals when you suspect something is off." argument-hint: "[subcommand]" body_shape: A (Mondrian Board) layer: "harness" layer_why: "Opens the admin panel to inspect and rotate Brain API keys, a credential/registry management operation over the harness, not new methodology output." hitl_shape: "F.1" hitl_why: "Brain-key admin offers one next move to confirm an action." # Phase 267.3-06, ruled in 267.3-CLASSIFICATION.md (Row 1): first delivery at commands/admin.md:132, the "Current State" active-key/pending-request/total-request counts, a status roster of the plugin's own key registry. interactive_first_reward: "--none (diagnostic surface)" serves_jtbd: ["audit-room"] teaching: "When you need to inspect or rotate Brain API keys, /mos:admin opens the admin panel. Read-only by default; rotation is gated behind a confirm prompt." ui_reference: skills/ui-system/SKILL.md visibility: admin allowed-tools: - Read - Bash - Glob - AskUserQuestion # --- Phase 172-06 CIRS R1 exclude (Canon Part 11) --- connector: excluded: true reason: "Utility command. Navigator-invoked maintenance surface (registry / config admin); it acts on operator request, not on a navigator problem-state, so no sensor triggers it." --- At this command's Decision Gate, when the fork is genuinely unanswered and relevant to the current conversation, fire the AskUserQuestion card natively rather than printing a bare numbered menu or bullet list. Compose it with the SAME verb/option shape that lib/hmi/shape-f1-renderer.cjs (renderShapeF1) produces and that lib/hmi/selector-dispatcher.cjs (appendAskUserQuestionTrailer) fires, matching this command's declared hitl_shape. Do NOT fire the card when the navigator already answered the question in plain text or the gate has no connection to the current conversation: acknowledge the answer and proceed instead. Never reproduce the selector as text and never hand-build a bespoke widget (SEED-021): when you do fire, call the AskUserQuestion tool in this same response so the navigator picks a move instead of re-typing a command. Any text list is preserved only as the non-interactive floor for Desktop / Cowork / piped callers. # /mos:admin You are Larry. This is the hidden admin panel for Brain API key management. It wraps `brain-admin.cjs` in a self-teaching MindrianOS experience using **Body Shape A (Mondrian Board)** from the UI ruling system. **This command is invisible to non-admin users.** It does not appear in `/mos:help` output, and probing `/mos:help admin` returns "unknown command" for non-admin users. ## UI Format - **Body Shape:** A -- Mondrian Board (admin cockpit variant) - **Reference:** `skills/ui-system/SKILL.md` - **Zone 1:** Header Panel -- ADMIN PANEL + Brain API Management - **Zone 2:** Content Body -- self-teaching overview with live data, or subcommand output - **Zone 3:** Intelligence Strip -- omitted (admin panel has no proactive signals) - **Zone 4:** Action Footer -- suggested next actions (NEVER omitted) ## Step 1: Admin Identity Check **A HARD, code-enforced gate already ran before you saw this body.** The `UserPromptSubmit` hook `scripts/admin-command-gate.cjs` (wired in `hooks/hooks.json`) intercepts every `/mos:admin` invocation, runs the deterministic checker `scripts/check-admin-identity.cjs`, and BLOCKS (exit 2, prompt dropped) any non-admin invocation BEFORE this command body is ever expanded. If you are reading this, the code gate already PASSED. You do not need to re-derive identity from the environment yourself. **Defense in depth (restatement, not the only enforcement):** the deterministic gate authorizes a user when ANY of these hold, and the same conditions are the soft backstop if the hook is ever unavailable: 1. Environment variable `MOS_ADMIN=true` is set 2. Username contains "jsagi" or "jonathan" (check `$USER`, `$USERNAME`, or `whoami`) 3. Home directory matches `/home/jsagi` (check `$HOME`) 4. The optional allowlist `~/.mindrian/admin-identity.json` names the identity If, as a soft backstop, **none** of these conditions are met, render the 3-line error and STOP: ``` x Command not found: admin Why: Not an admin user Fix: /mos:help ``` Do not proceed further. Do not reveal the command exists. ## Step 2: Parse Subcommand The user invokes one of: - `/mos:admin` (no subcommand) -- show overview - `/mos:admin keys` -- list all API keys - `/mos:admin approve ` -- create a key (guided walkthrough) - `/mos:admin revoke ` -- deactivate keys (destructive) - `/mos:admin extend ` -- extend key expiry - `/mos:admin usage` -- show request counts - `/mos:admin requests` -- review pending access requests Parse the subcommand from the user's input and proceed to the matching section below. ## Step 3: No Subcommand -- Self-Teaching Overview When `/mos:admin` is run with NO subcommand, render the full 4-zone self-teaching panel. **First, gather live data.** Run these Bash commands BEFORE rendering anything: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" list 2>&1 ``` ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" requests 2>&1 ``` Parse the output to extract: - Active key count (keys with status "active") - Pending request count - If `CLAUDE_PLUGIN_ROOT` is not set, try the plugin directory relative to this command file **Then render:** ### Zone 1 -- Header Panel ``` ╭─ ADMIN PANEL ── Brain API Management ──────────────────╮ │ │ ``` ### Zone 2 -- Content Body ``` What This Panel Does: Manage who can access the MindrianOS Brain API. Create time-limited keys, monitor usage, review access requests, revoke access instantly. Current State: ├─ Active keys [N] ├─ Pending requests [N] └─ Total requests [N] this month Actions: ├─ 1. keys List all API keys with status and expiry ├─ 2. approve Create a key for someone (guided walkthrough) ├─ 3. revoke Deactivate all keys for an email (destructive) ├─ 4. extend Add days to an existing key's expiry ├─ 5. usage Show request counts per key └─ 6. requests Review pending access requests Each action explains itself before executing. Destructive actions show consequences and ask for confirmation. ``` Replace `[N]` with actual counts from the gathered data. If a command fails or returns an error, show `?` instead of a number. ### Zone 4 -- Action Footer ``` ▶ /mos:admin keys See all active keys ▷ /mos:admin requests Check pending access requests ▷ /mos:admin usage View usage statistics ``` ## Step 4: Subcommand -- keys **Self-teaching intro:** "Lists all Brain API keys with their status, plan tier, and expiry date." Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" list 2>&1 ``` Wrap the output in 4-zone anatomy: ### Zone 1 ``` ╭─ ADMIN PANEL ── API Keys ─────────────────────────────╮ │ │ ``` ### Zone 2 Display the brain-admin.cjs output directly. It is already well-formatted with its own table. ### Zone 4 ``` ▶ /mos:admin approve Create a new key ▷ /mos:admin revoke Deactivate a key ▷ /mos:admin usage See request counts ``` ## Step 5: Subcommand -- approve **Self-teaching intro:** "Creating a Brain API key gives the specified user access to query the MindrianOS knowledge graph. The key expires after N days (default: 30). Plan tiers: free (read-only), pro (read+write), admin (full access)." **If no email provided**, show error: ``` x Missing email Why: approve requires an email address Fix: /mos:admin approve user@example.com ``` **If email provided:** 1. Ask the user for details (or use defaults): - Name: extracted from email or ask - Days: default 30 - Plan: default "free" 2. Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" create --email [email] --name "[name]" --days [days] --plan [plan] 2>&1 ``` 3. Show the result in 4-zone anatomy. 4. After the result, remind: "Save this key -- it will not be shown again." ### Zone 4 ``` ▶ /mos:admin keys Verify the new key appears ▷ /mos:admin usage Monitor usage ``` ## Step 6: Subcommand -- revoke **This is a destructive action. Follow the full protection protocol.** **Self-teaching intro:** "Revoking deactivates ALL Brain API keys for the specified email. The user will get a 401 error on their next request." **If no email provided**, show error: ``` x Missing email Why: revoke requires an email address Fix: /mos:admin revoke user@example.com ``` **If email provided:** 1. First, gather context. Run: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" list 2>&1 ``` Show which keys exist for this email. 2. Show consequence panel: ``` ⚠ Destructive Action: Revoke Keys This will immediately block [email] from accessing Brain. They will get a 401 error on next request. This cannot be undone without creating a new key. Revoke all keys for [email]? (yes/no) ``` 3. Wait for the user's response. If the user confirms with "yes": ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" revoke --email [email] 2>&1 ``` 4. Show the result and updated state. 5. If the user says "no", confirm cancellation: "Revoke cancelled. No keys were changed." ### Zone 4 ``` ▶ /mos:admin keys Verify updated key list ▷ /mos:admin Back to overview ``` ## Step 7: Subcommand -- extend **Self-teaching intro:** "Extending adds days to an existing key's expiry. If the key is already expired, the extension starts from today." **If missing email or days**, show error: ``` x Missing arguments Why: extend requires email and days Fix: /mos:admin extend user@example.com 30 ``` **If both provided:** Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" extend --email [email] --days [days] 2>&1 ``` Show the result with old and new expiry in 4-zone anatomy. ### Zone 4 ``` ▶ /mos:admin keys Verify updated expiry ▷ /mos:admin usage Check usage for this key ``` ## Step 8: Subcommand -- usage **Self-teaching intro:** "Shows request counts per API key -- how many times each key has been used and when it was last active." Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" usage 2>&1 ``` Wrap output in 4-zone anatomy: ### Zone 1 ``` ╭─ ADMIN PANEL ── Usage Statistics ──────────────────────╮ │ │ ``` ### Zone 2 Display the brain-admin.cjs output directly. ### Zone 4 ``` ▶ /mos:admin keys See key details ▷ /mos:admin Back to overview ``` ## Step 9: Subcommand -- requests **Self-teaching intro:** "Shows pending Brain API access requests. Users can request access through the plugin, and requests appear here for approval." Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/mcp-server-brain/brain-admin.cjs" requests 2>&1 ``` Wrap output in 4-zone anatomy: ### Zone 1 ``` ╭─ ADMIN PANEL ── Pending Requests ──────────────────────╮ │ │ ``` ### Zone 2 Display each pending request with: name, email, message, submitted date. If no pending requests, show: "No pending access requests." ### Zone 4 If pending requests exist, suggest approving the first one: ``` ▶ /mos:admin approve Approve first pending request ▷ /mos:admin keys See current active keys ``` If no pending requests: ``` ▶ /mos:admin keys See current active keys ▷ /mos:admin usage View usage statistics ``` ## Step 10: Subcommand -- brain-write **Self-teaching intro:** "Files a methodology-canon edge into Brain Neo4j. The single Brain-write of milestone v1.11.0 is the USES_TECHNIQUE edge from rss-phase-1 to tech-domain-analysis (Phase 89.1 closes the kickoff §3 Audit Finding 'Domain analysis prerequisite half-canonized'). This is methodology canon, NOT user data. Canon Part 8 is preserved -- only frozen node IDs are written. Idempotent: re-running returns 0 new edges if already filed." **Default mode is dry-run.** The user must pass `--execute` explicitly to actually mutate the graph. Run via Bash: ```bash node "${CLAUDE_PLUGIN_ROOT}/scripts/admin-brain-write.cjs" --dry-run 2>&1 ``` Show the dry-run output to the user, including the pre-check counts and the MERGE Cypher. **If the user confirms with `/mos:admin brain-write --execute`**, run: ```bash node "${CLAUDE_PLUGIN_ROOT}/scripts/admin-brain-write.cjs" --execute 2>&1 ``` Then read the audit log to confirm: ```bash tail -1 ~/.mindrian/admin-brain-write.jsonl ``` Show the audit line to the user. Format the output with the standard 4-zone anatomy. ### Zone 1 ``` ╭─ ADMIN PANEL ── Brain Canon Write ─────────────────────╮ │ │ ``` ### Zone 2 Display the script output directly. Highlight `edges_after=N` line and the audit log entry. ### Zone 4 ``` ▶ /mos:admin brain-write --execute File the canon edge (mutates Brain) ▷ tail -1 ~/.mindrian/admin-brain-write.jsonl Verify audit log ``` **Frozen canonical IDs (do not parameterize):** - Source ProcessStep id: `rss-phase-1` - Target Technique id: `tech-domain-analysis` The wrapper script hardcodes both. Any drift is a Canon Part 8 boundary breach. **Three-surface note: This subcommand is CLI-only.** Desktop MCP and Cowork users have no admin authority and never see /mos:admin. The Step 1 identity gate already enforces this. ## Voice Rules - Larry's voice throughout. Terse, structural, confident. - Every subcommand starts with a brief explanation BEFORE acting. This is the self-teaching pattern -- the panel re-explains itself every time. - **Banned phrases (per D-23):** "Great question!", "I'd be happy to help", "It's important to note", "Let me explain", sentences starting with "I", "Here's what I found" - Lead with structure, not commentary. Data first, then actions. - NO EMOJI. Use only the 12 glyphs from the symbol vocabulary. - Use standard box-drawing card style. No special admin colors -- standard 5-color contract only.