---
path: /studio/isis/cli-surface
surface: studio
domain: isis
auth:
  signed-in + studio entitlement; Studio Isis production boundary hard-blocks
  this AAA-only route. Automated lane verification uses the explicit
  localhost-only E2E bypass.
source: apps/oshun/web/src/app/studio/isis/cli-surface/page.tsx
status: walked
last_walked:
  '2026-07-23 automated desktop Chromium + Pixel 7 mobile walk — production
  hard-block, localhost-only lane entry, exact BFF catalog and resolution
  contracts, admin-scope failure, input bounds, request-local disposition,
  deterministic output, documented-route status, keyboard-accessible result
  scrolling, touch target, responsive containment, and applicable axe verified'
---

# Isis CLI Surface

## Purpose

Request-local, non-authoritative preview of deterministic CLI token resolution.
The operator supplies both the command registry and query tokens. The resolver
classifies each query as exact, alias, unique prefix, ambiguous, or unknown and
returns a summary plus candidate names. It does not load a canonical command
catalog, execute commands, retain sessions, or create diagnostic, permission,
audit, governance, approval, or release evidence.

Exact disposition:
`request_local_non_authoritative_cli_token_resolution_preview`.

## Entry points

- Sibling quick-action card from `/studio/isis/account-protection`
- Embedded as the CLI Surface lane in `/studio/isis/cli`
- Studio index (`/studio`)
- Direct URL / bookmark (AAA-gated)

## Layout regions

`page.tsx` mounts `ShellLayout active="studio"` and three panels.

- **Workspace panel** (`data-isis-cli-surface-workspace`):
  - `<h1>` "Isis CLI Surface Workspace" (`WorkspaceHeading`)
  - Honest summary (`data-isis-cli-surface-summary`)
  - Resolver lane (`data-cli-lane`, `<h2>` "Request-local CLI token resolution
    preview")
  - Resolution Boundary (`data-cli-disposition`) with four cards:
    caller-supplied registry, request-only computation, no command execution,
    and no operational authority
  - Labeled JSON form (`data-cli-form`) with contract limits and a
    pending-disabled 44-pixel submit control
  - Result summary and keyboard-focusable horizontally scrollable table
- **Route map panel** (`data-isis-cli-surface-route-map`): one `mounted-preview`
  entry and four `documented-contract` entries
- **Quick-actions panel**: links to `/studio/isis/account-protection` and
  `/studio`

## States

- [ ] **Loading** — `data-cli-loading` while the catalog contract loads
- [ ] **Unauthorized** — `data-cli-unauthorized` on admin-scope 401/403
- [ ] **Error** — `data-cli-error` for unavailable, non-2xx, or malformed /
      authority-inflated catalog responses
- [ ] **Ready** — exact catalog accepted; boundary and form render
- [ ] **Resolving** — submit is disabled and labels itself "Resolving…"
- [ ] **Result** — exact result envelope accepted into `data-cli-result`
- [ ] **Resolution error** — local JSON failure, bounded-contract rejection,
      authorization failure, network failure, or malformed / authority-inflated
      response in `data-cli-resolve-error`

## Interactions

### Preview resolution (`data-cli-form`)

- [ ] **Registry and query JSON** (`data-cli-payload`) — caller supplies exactly
      `commands` and `queries`
- [ ] **Preview resolution** (`data-cli-submit`) — POSTs the bounded payload to
      `/v1/admin/isis/cli-surface/resolve`; it does not execute a command
- [ ] **Resolution result** (`data-cli-result`) — query rows expose match type,
      resolved command, and candidates; the scroll region has a named keyboard
      focus target

### Route map

- [ ] **Mounted preview** ×1
- [ ] **Documented route shapes without pages or authority** ×4

### Quick-actions

- [ ] **Open Isis Account Protection workspace** →
      `/studio/isis/account-protection`
- [ ] **Back to Studio workspace index** → `/studio`

## Data & contracts

- **Catalog read**: `GET /v1/admin/isis/cli-surface`
  - exact keys: `generatedAt`, `resolver`, `limits`, `disposition`
  - explicitly `cache-control: no-store`
- **Resolution calculation**: `POST /v1/admin/isis/cli-surface/resolve`
  - exact input keys: `commands`, `queries`
  - limits: 256 commands, 32 aliases per command, 1,024 queries, 128 characters
    per whitespace-free token
  - exact success keys: `ok`, `result`, `disposition`
  - deterministic pure calculation; no durable write
  - explicitly `cache-control: no-store`
- **Persistence / retention**: none / request-only
- **Registry authority**: caller-supplied; no canonical catalog
- **Execution / state**: no command execution, session state, retry,
  cancellation, diagnostic, trace, permission, or audit control
- **Governance / release**: no record or authority
- **Auth**: admin-scoped fail-closed per BFF request; AAA-gated Studio route
  behind the signed-in + studio proxy gate
- **Component sources**:
  - `apps/oshun/web/src/components/studio/StudioIsisCliSurfaceWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisCliSurfaceRouteMap.ts`
- **Backend sources**:
  - `apps/oshun/bff/src/routes/admin-isis-cli-surface.ts`
  - `apps/oshun/bff/src/isis/cli-command-store.ts`

## Cross-references

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  - [`studio-isis-cli.md`](./studio-isis-cli.md)
  - [`studio-isis-account-protection.md`](./studio-isis-account-protection.md)
  - [`studio-isis-client.md`](./studio-isis-client.md)

## Open questions / known gaps

- [ ] Scene, export, revision, and governance paths are documented shapes only;
      they have no pages or operational authority
- [ ] A canonical command catalog, command/session execution service,
      diagnostic/audit evidence store, governance workflow, and release
      authority are not bound here