# CLI Audit: Complete Noun/Verb Taxonomy

**Author:** Benjamin Booth  •  **Date:** 2026-04-13  •  **Status:** Draft

---

## Design Principles

1. **Axiom (`axi`) vs NeutronOS (`neut`)**: Axiom owns domain-agnostic nouns. NeutronOS extends with nuclear-specific nouns. Branding swaps the binary name but the taxonomy is the same.
2. **Noun-verb pattern**: `axi <noun> <verb> [args] [--flags]`
3. **Progressive disclosure**: Common verbs first (`list`, `show`, `create`), advanced verbs discoverable via `--help-all`.
4. **Consistency**: Every noun that manages lifecycle artifacts supports `create`, `list`, `show`, `delete`. Every noun with state supports `status`.
5. **`--json` everywhere**: All commands support JSON output for scripting.
6. **`--confirm` on destructive ops**: `delete`, `drop`, `uninstall`, `archive` require confirmation or `--confirm` flag.
7. **Shorthand aliases**: `-o` output, `-m` message, `-f` format, `--json`.

---

## Layer 1: Axiom-Level Nouns (`axi`)

These ship with the Axiom framework. Domain-agnostic.

### Core (not extensions)

| Noun | Verb | Description | Status |
|------|------|-------------|--------|
| `config` | *(wizard)* | Interactive onboarding | Shipped |
| `ext` | `list`, `init`, `check`, `docs` | Extension management | Shipped |
| `doctor` / `dr` | *(diagnostic)* | AI-powered env diagnostics | Shipped |

### Platform Utilities

| Noun | Verb | Description | Status |
|------|------|-------------|--------|
| `status` | *(dashboard)* | System health dashboard | Shipped |
| `update` | `check`, `apply` | Self-update | Shipped |
| `settings` | `get`, `set` | Configuration | Shipped |
| `db` | `migrate`, `status`, `seed` | Database lifecycle | Shipped |
| `test` | `run` | Test orchestration | Shipped |

### Agents

| Noun | Verb | Description | Agent | REPL Role | Status |
|------|------|-------------|-------|-----------|--------|
| `chat` | *(interactive)* | Conversational agent | WALL-E | Loop | Shipped |
| `signal` | `status`, `ingest`, `scan`, `draft`, `review`, `flush` | Signal pipeline | EVE | Read | Shipped |
| `pub` / `doc` | `draft`, `push`, `pull`, `status` | Publisher + content gate | PR-T | Print | Shipped |
| `mo` | `cleanup`, `vitals` | Infrastructure steward | M-O | Infra | Shipped |
| `release` | *(TBD)* | Build, tag, ship | BURN-E | Ship | Planned |
| `agents` | `start`, `stop`, `status`, `logs`, `register-launchd` | Agent lifecycle | — | — | Planned |

### Data & RAG

| Noun | Verb | Description | Status |
|------|------|-------------|--------|
| `rag` | `load-community`, `sync`, `index`, `search`, `status`, `reindex` | RAG index management | Shipped |
| `note` | *(quick capture)* | Quick notes → RAG-indexed | Shipped |
| `serve` | *(start server)* | HTTP API + OpenAI-compat endpoint | Shipped |
| `connect` | `teams`, `--check`, `--json` | External credential management | Planned |

---

## Layer 2: New Axiom Nouns (Classroom / Evals / Research)

### `axi course` — Course Artifacts (ArtifactRegistry)

A Course is a reusable template: syllabus, learning objectives, corpus refs, system prompt, questionnaire manifests, eval suites.

| Verb | Arguments | Description |
|------|-----------|-------------|
| `create` | `--name`, `--template` | Scaffold a new course manifest |
| `validate` | `<path>` | Schema-validate a course.yaml |
| `publish` | `<path>`, `--confirm` | Promote draft → published (runs eval gate) |
| `list` | `--status`, `--json` | List courses in registry |
| `show` | `<id>` | Display course details |
| `share` | `<id>`, `--to <node>` | Federate course to peer node |
| `delete` | `<id>`, `--confirm` | Remove a course (fails if active classrooms exist) |

**Lifecycle:** `draft → review → published → deprecated → archived`

### `axi classroom` — Live Course Instances

A Classroom is Course + cohort + date range. Has state machine lifecycle.

| Verb | Arguments | Description |
|------|-----------|-------------|
| `create` | `--course <id>`, `--students <yaml>`, `--start <date>` | Instantiate classroom from course |
| `status` | `<id>` | Classroom state, enrollment counts, active signals |
| `student` | `<id> <student_id>` | Per-student briefing (activity, scores, signals) |
| `objectives` | `<id>` | Per-objective coverage heatmap |
| `classify` | `<id>`, `--batch` | Run/re-run interaction classifier |
| `export` | `<id>`, `--format parquet\|csv`, `--anonymize` | Research dataset builder |
| `quiz` | `import --file <csv> --assessment pre\|mid\|post` | Import pencil-and-paper scores |
| `survey` | `<id>`, `--type nps\|exit` | Trigger a survey questionnaire |
| `archive` | `<id>`, `--confirm` | Transition completed → archived |
| `delete` | `<id>`, `--confirm` | Delete classroom and all data (irreversible; must be archived first) |
| `join` | `<id>` | Student joins an active session (presence) | **Deferred** |
| `presence` | `<id>` | Who's connected/joined/absent | **Deferred** |
| `roll-call` | `<id>` | Prompt all students to join | **Deferred** |

**Lifecycle:** `provisioning → enrolled → active → completing → completed → archived`

### `axi eval` — Evaluation Framework

| Verb | Arguments | Description |
|------|-----------|-------------|
| `create-suite` | `--type <eval_type>`, `--name <name>` | Scaffold eval suite YAML |
| `run` | `--suite <id>`, `--target <endpoint>` | Execute eval suite |
| `compare` | `--suite <id>`, `--baseline <target>`, `--candidate <target>` | Side-by-side comparison |
| `history` | `--suite <id>` | Trend over time |
| `report` | `--run <run_id>`, `--format md\|html` | Generate eval report |
| `gate` | `--suite <id>`, `--threshold <float>` | Pass/fail check (for CI/publish gates) |

**No `delete` needed** — eval runs are append-only audit records. Suites are ArtifactRegistry items with lifecycle deprecation.

### `axi research` — CURI-O Research Loops

| Verb | Arguments | Description |
|------|-----------|-------------|
| `start` | `<objective>`, `--max-iterations`, `--budget` | Launch a new research loop |
| `status` | `<loop_id>` | Current iteration, convergence, sub-questions |
| `resume` | `<loop_id>` | Resume a paused/interrupted loop |
| `stop` | `<loop_id>` | Gracefully stop and promote current findings |
| `list` | `--status running\|converged\|stopped`, `--json` | List research loops |
| `show` | `<loop_id>` | Full loop state: hypothesis, evidence, convergence |
| `export` | `<loop_id>`, `--format md\|yaml\|json` | Export research report/state |
| `delete` | `<loop_id>`, `--confirm` | Delete loop and all iteration data |

**Why `axi research` not `axi curio`**: CLI nouns are generic English, not brand names (same principle as `axi model` not `axi corral`). CURI-O is the agent *behind* research, not the user-facing noun.

### `axi questionnaire` — Structured Q&A Engine

| Verb | Arguments | Description |
|------|-----------|-------------|
| `create` | `--name`, `--template begin\|end\|nps\|custom` | Scaffold questionnaire manifest |
| `validate` | `<path>` | Schema-validate a questionnaire YAML |
| `start` | `<id>`, `--classroom <id>`, `--students all\|<list>` | Activate for a cohort |
| `status` | `<id>` | Completion tracking per student |
| `export` | `<id>`, `--format csv\|parquet` | Structured response export |
| `delete` | `<id>`, `--confirm` | Delete questionnaire and all responses |

### `axi chat` (updates) — Multi-Participant & @Agent Addressing

These are enhancements to the existing `axi chat` primitive, not a new noun.

| Feature | Syntax | Description |
|---------|--------|-------------|
| `@agent` addressing | `@curio <directive>` | Direct-address any agent; WALL-E steps aside |
| Delegation visibility | *(automatic)* | When WALL-E delegates, user sees `@curio research "topic"` |
| `/invite` | `/invite @user` | Bring another human into the current chat |
| Shared loop context | *(automatic)* | Invited user sees full research loop state (hypothesis, contradictions, evidence) |
| Human-injected directives | `@curio add sub-question "..."` | Any participant can steer a running research loop |

**Why this is Axiom Chat, not a separate noun:** The research loop doesn't have a fixed participant count. `/invite` adds a human to the chat; the loop just processes inputs regardless of source. No new noun needed — this composes naturally with `axi chat` + `axi research`.

### `axi lti` — LTI 1.3 Tool Provider

| Verb | Arguments | Description |
|------|-----------|-------------|
| `register` | `--issuer <url>`, `--client-id <id>` | Register an LMS platform |
| `status` | | Show registered platforms, key expiry |
| `keys` | `--rotate`, `--export` | Manage JWKS keys |

---

## Layer 3: NeutronOS-Specific Nouns (`neut`)

These extend the Axiom CLI with nuclear domain commands. They are not part of Axiom core.

### Shipped

| Noun | Verb | Description | Status |
|------|------|-------------|--------|
| `model` | 24 verbs (init, validate, add, search, list, show, pull, lineage, clone, diff, export, audit, generate, lint, sweep, materials, share, receive, invite, contributors, status, review, reviews, resolve) | Physics model registry | Shipped (415+ tests) |
| `facility` | 9 verbs (list, show, install, uninstall, init, publish, materials, sync) | Facility packs | Shipped |
| `demo` | `run`, `reset`, `list` | Guided demos | Shipped |

### Planned

| Noun | Verb | Description |
|------|------|-------------|
| `twin` | `run`, `shadow`, `infer`, `rom-train`, `rom-deploy`, `rom-validate`, `compare`, `drift`, `report` | Digital twin hosting |
| `log` | `query`, `entry create`, `export` | Reactor operations log |
| `data` | `query`, `pipeline status`, `backfill` | Data platform |
| `media` | `ingest`, `search`, `tag`, `link` | Media library |
| `infra` | `health`, `logs`, `deploy` | Infrastructure |
| `state` | `inventory`, `backup`, `restore`, `retention`, `cleanup` | State management |

---

## Slash Commands (inside `axi chat` / `neut chat`)

Slash commands are the conversational action layer inside the chat REPL. Each maps to a CLI command but is invoked conversationally.

### Existing

| Command | Maps to | Description |
|---------|---------|-------------|
| `/ask` | mode switch | Return to read-only mode |
| `/plan` | mode switch | Switch to plan mode |
| `/agent` | mode switch | Switch to agent mode |
| `/signal` | `axi signal` | Signal operations |
| `/pub` | `axi pub` | Publishing operations |
| `/model` | `neut model` | Model registry operations |

### New (Classroom/Research)

| Command | Maps to | Description |
|---------|---------|-------------|
| `/research <topic>` | `axi research start` | Start a CURI-O research loop |
| `/research status` | `axi research status` | Check current loop |
| `/submit <assignment>` | WF-10 submission | Submit student work |
| `/help-request` | WF-6 | Formal help ticket |
| `/quiz` | WF-3 (Mode B) | In-platform assessment |
| `/checklist` | WF-2 | View onboarding checklist |
| `/objectives` | `axi classroom objectives` | View learning objective coverage |

---

## Cross-Cutting Consistency Audit

### Verb Consistency Matrix

Every lifecycle-managed noun should have a consistent verb surface:

| Verb | course | classroom | eval suite | research | questionnaire | model | facility |
|------|--------|-----------|------------|----------|---------------|-------|----------|
| `create` | Yes | Yes | `create-suite` | `start` | Yes | `init` | `init` |
| `list` | Yes | *(via status)* | *(via history)* | Yes | *(via status)* | Yes | Yes |
| `show` | Yes | *(via status)* | *(via report)* | Yes | *(via status)* | Yes | Yes |
| `delete` | Yes | Yes | No (audit) | Yes | Yes | No (versioned) | `uninstall` |
| `validate` | Yes | — | — | — | Yes | Yes | — |
| `export` | — | Yes | — | Yes | Yes | Yes | — |
| `status` | *(lifecycle)* | Yes | — | Yes | Yes | Yes | — |
| `share` | Yes | — | — | — | — | Yes | — |

### Flag Consistency

| Flag | Meaning | Global |
|------|---------|--------|
| `--json` | JSON output | All commands |
| `--confirm` | Skip interactive confirmation | Destructive ops |
| `--format` / `-f` | Output format (md, csv, parquet, html) | Export commands |
| `-o` / `--output` | Output file path | Export/report commands |
| `-m` / `--message` | Message/description | Create/add commands |

### Naming Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| `axi research` vs `axi curio` | `research` | CLI nouns are generic English, not agent brand names |
| `axi eval create-suite` vs `axi eval create` | `create-suite` | `eval` is overloaded; suite is the artifact being created |
| `axi classroom quiz import` vs `axi quiz import` | `classroom quiz` | Quiz is a verb within classroom context, not its own noun |
| `axi questionnaire` vs `axi survey` | `questionnaire` | Questionnaire is the engine; surveys and interviews are instances |
| `axi classroom delete` vs `axi classroom drop` | `delete` | Consistent with `course delete`, `research delete`, `questionnaire delete` |
| `axi classroom archive` separate from delete | Yes | Archive preserves data; delete destroys it. Two-step: archive then delete |

---

## Deferred: Presence System

Student presence (real-time connection state, explicit session join, attendance tracking) surfaces here via `classroom join` / `classroom presence` / `classroom roll-call` but is a separate domain requiring its own PRD. Key concerns:

- **Real-time infrastructure** — WebSocket heartbeats, connection state, reconnection handling
- **Privacy** — always-on presence tracking has IRB/GDPR implications; opt-in vs. implicit
- **Research design** — attendance vs. engagement vs. time-on-task are distinct metrics
- **Sync vs. async** — distinguishing "student is present for a live session" from "student is using the tool at 2am"
- **Slash command**: `/join` in chat for students

The CLI verbs are reserved in the classroom noun table above (marked **Deferred**) so the surface area is claimed. Implementation blocked on the presence PRD.

---

## Open Questions

1. **`axi classroom list`** — Should this be a separate verb or is `axi classroom status` (no args) sufficient to show all classrooms? **Recommendation:** Add `list` for consistency. `status <id>` shows one classroom; `list` shows all.
2. **`axi eval delete-suite`** — Eval runs are append-only, but should suite *definitions* be deletable? **Recommendation:** No — use ArtifactRegistry `deprecated` lifecycle. Runs reference suites; deleting breaks provenance.
3. **`axi research share`** — Should research loops be federable? The architecture doc says yes (research findings federate). **Recommendation:** Defer to post-MVP. The federation protocol handles this automatically during loop execution. A manual `share` verb isn't needed until Mode 2/3 federation.
4. **Bare `axi course` / `axi classroom`** — What does running the noun with no verb do? **Recommendation:** Show brief status summary (same pattern as bare `axi` → interactive chat).

---

## Summary: Complete Command Count

| Layer | Nouns | Verbs | Status |
|-------|-------|-------|--------|
| Axiom Core (shipped) | 12 | ~35 | Shipped |
| Axiom New (classroom/evals/research) | 5 | ~35 | This audit |
| NeutronOS Shipped | 3 | ~41 | Shipped |
| NeutronOS Planned | 6 | ~25 | Planned |
| **Total** | **26** | **~136** | |

---

*This audit should be reviewed alongside:*
- `docs/prds/prd-classroom.md` — Classroom PRD
- `docs/prds/prd-evals.md` — Evals PRD  
- `docs/working/curio-research-loop.md` — Research loop design
- `Neutron_OS/docs/prds/prd-neut-cli.md` — Existing CLI PRD
