# Ujima showcase

An internal system showcase for Malkio: what Ujima is, its state today, and what's next. Static
HTML, no build step, generated from the real CLI, schemas, templates, docs, and one real deployed
workspace as of **2026-07-18**.

## How to open it

```bash
node scripts/serve-showcase.mjs --port 8788      # from the Ujima repo root
```

Then open `http://localhost:8788/index.html`. Search and the roadmap board both `fetch()` JSON and
so need `http://`; every other page also renders correctly opened directly from `file://` (double-click
`index.html`) except those two features, which degrade to an honest message rather than a dead box.

## What's here

- **`index.html`** — hub: 6 surfaces, 5 component categories, filter box.
- **6 surface pages** (`surface-*.html`) — full-frame renders: the CLI, `ujima brief`, workspace
  anatomy, the Convene/D.O.P.E. state machine, `doctor`+`sweep`, and the live caspera-fleet status.
- **5 category pages** (`components-*.html`) — 47 component cards: 19 CLI verbs, 4 JSON schemas,
  5 templates, 11 Convene phases, 8 design docs.
- **`roadmap.html` / `roadmap.json`** — a hand-curated board using Ujima's own maturity ladder
  (M0–M5) instead of an invented tier system.
- **`search-index.json`** — generated by `scripts/build-search-index.mjs`, which parses the
  rendered markup (never hand-maintained). Regenerate after any copy change:
  `node scripts/build-search-index.mjs`; `--check` for CI.
- **`assets/site.css` / `assets/site.js`** — shared chrome, copied unchanged from the showcase skill.
  Feedback (🐞/✨ buttons) degrades to an honest "no public tracker" message: `showcase-repo` is
  intentionally empty because Ujima has no hosted public repo, so no GitHub-issue fallback is offered.

## Written inventory (the count the build was checked against)

| Group | Count | Source |
|---|---|---|
| Surfaces | 6 | CLI, brief, workspace tree, Convene state machine, doctor/sweep, live fleet |
| CLI verb cards | 19 | `cli/ujima.py`'s own `argparse` subcommand list |
| Schema cards | 4 | `spec/schemas/*.json` |
| Template cards | 5 | `templates/*.md` |
| Convene phase cards | 11 | `CONVENE_PHASES` tuple, `cli/ujima.py:927` |
| Design doc cards | 8 | `docs/00-INTENT.md` … `docs/07-CONVENE-DOPE.md` |
| **Total components** | **47** | matches `showcase.config.json`'s `expected.components`; `build-search-index.mjs` reported exactly 47, 0 warnings |

## Discrepancies found (code vs. docs/brief) — the most valuable output of this exercise

1. **"Seven verbs" vs. 19 subcommands.** `README.md` and `skills/ujima-core/SKILL.md` both teach
   "the seven verbs" (brief, send/reply, inbox/read/archive, status set, log, checkpoint,
   sweep+doctor) as the whole interface. The shipped CLI has **19** subcommands: `init`, `agent`,
   `whoami`, `ledger`, `render`, `lock`, `unlock`, `poll`, and the entire `convene` family (9
   sub-subcommands) exist in code and are absent from the seven-verb pitch. Shipped code wins —
   this showcase lists all 19 on `components-verbs.html`, with the discrepancy called out again
   on `surface-cli.html`.
2. **Convene is further along than its own doc claims.** `docs/07-CONVENE-DOPE.md`'s status line
   reads *"DESIGN APPROVED (2026-07-02) — pending written-spec review before implementation
   planning."* That reads as pre-implementation. But `cli/ujima.py` already ships a working
   `convene` command (`start`, `assisted`, `status`, `phase`, `discuss`, `team`, `escalate`,
   `resume`, `close`) with the full 11-phase transition graph mechanically enforced — including
   the "cannot enter TEAM_SELECT without operation_shape", "cannot enter EXECUTE without BRIEF.md",
   and "CLOSED requires a checkpoint" hard rules described in the doc. The **mechanism** is built;
   what's missing is the **agent-side workflow** each phase is supposed to run (case-file assembly,
   judgment classification, scout recon) — that part genuinely is still prose-only. The roadmap
   reflects this split: `convene-phase-machine` is `resolved` at v1.0.0; `convene-workflow` is not.
3. **`lane: heavy|light` is referenced before it exists.** `docs/07-CONVENE-DOPE.md` §16 already
   writes scout-selection logic that assumes an agent's `lane` field — but `agent.schema.json` has
   no such field yet. Flagged, not fixed, per the fidelity rule; it's `components-schemas.html`'s
   `agent-schema` card and a roadmap item.
4. **Fleet cutover is a real, named decision, not silence.** `NAMING.md` states plainly that
   `collab-v3` (backing `caspera-fleet`) is deliberately left untouched until Ujima is proven in
   parallel — this showcase states the same thing on `surface-fleet.html` and as a `roadblocked`-style
   roadmap item, rather than implying migration is either done or forgotten.

No other gaps were found between the docs and the code on the surfaces this showcase covers —
worth stating plainly, since finding *zero* discrepancies is usually a sign of reading the docs
instead of the code, not a sign of a docs-perfect project.

## Faithful vs. approximated

**Faithful (verbatim from the repo, byte-for-byte or near enough):**
- The `ujima --help` transcript, CLI cap constants (300/2,000/4,000/8,000 chars, 600s lock TTL,
  30/240/1,440-minute escalation timers), the 7 secret-detection patterns, the `doctor` check list,
  the `sweep`'s four jobs, the `CONVENE_PHASES` tuple and its transition rules, all four JSON
  Schema excerpts, all five template excerpts, the `GENERATED` banner, and every doc excerpt on
  `components-docs.html`.
- `surface-fleet.html`'s 9-agent table and protocol version are read directly from
  `fleet-collab/STATUS.md` and `fleet-collab/.collab/workspace.json` — real, current state of the
  one live consumer, not sample data.

**Composed for this showcase (disclosed, not hidden):**
- Ujima has **no UI** — it's a protocol plus a CLI, so there is nothing to screenshot. Every
  surface is a *staged terminal/diagram rendering* of real output and real file structure, not a
  captured screen. The terminal chrome (dot-bar window frame), the file-tree layout, and the
  Convene phase diagram are original compositions built to present real content, clearly labeled
  as such.
- `surface-brief.html`'s demo data (agent names `reva`/`jorin`, message ids, ledger entries) reuses
  the **same example names the project's own `README.md` quickstart uses** — not invented, not
  real internal names, and internally consistent (the unread-mail count, the ledger entries, and
  the checkpoint reference all agree with each other).
- The visual identity (dark panel chrome; the green/gold/red three-circle mark; monospace for
  everything that is genuinely terminal output, sans-serif only for the showcase's own prose) is
  **invented for this showcase**, not extracted from a product design system — because the product
  doesn't have one. The three-color mark is a tasteful, non-literal nod to the Kwanzaa/Nguzo Saba
  naming heritage (`NAMING.md`): Ujima = collective work and responsibility. It does not reproduce
  any flag or official symbol.
- The roadmap's columns are Ujima's own maturity ladder (`docs/04-NEXT-LEVEL.md`, M0–M4) with one
  addition: **M5 · Federated** is *not* in that document — it's this showcase's own name for "the
  tier after M4," added because Malkio's brief asked for it explicitly. `roadmap.json`'s own
  `_comment` field states this so a future editor doesn't mistake it for a documented level.

**Not built, on purpose:**
- No screenshot capture pass (`capture-screenshots.mjs`) — there is no external listing (app store,
  README badge) linking a pinned filename, so there's nothing that needs a validated PNG; the
  audience opens the HTML directly.
- No feedback backend (`functions/api/feedback.js`) — this is a single-viewer internal tool, not a
  public site with its own intake board. The client-side fallback still works honestly (see above).
- No CI wiring (`build-search-index.mjs --check`) — nothing currently commits to this repo on a
  schedule; regenerate the index by hand after editing copy.

## Bugs / gaps surfaced by building this

- `agents/koda` (in the real `fleet-collab` workspace) is missing `heartbeat.md` — `doctor` would
  flag this as a warning today if run against that workspace. Not fixed here; logged.
- The real `fleet-collab/STATUS.md` shows 8 of 9 agents with no status ever set, months after the
  workspace's `created` timestamp (`2026-07-02`) — consistent with Convene's "point agents at a
  target" problem being unsolved today: nothing currently *drives* an idle agent to pick up work
  without a human assigning it by hand.