OZ Assist

OZ Assist is the user-side in-agent surface described in PRD.md: a structured, version-aware workflow for preventing integration failures before code is run.

It is intentionally isolated under packages/assist:

• cli/: local oz-assist command runner.
• mcp/: stdio MCP server entrypoint.
• src/framework/: artifact contracts, workspace state, retrieval, orchestration, and verification.
• src/mcp/: MCP tool definitions and handlers.
• skills/: the installable OZ Assist agent skill.
• agents/: role prompts for researcher, verifier, and remediation planning subagents.

Solution Engineer Flow

The default in-agent entrypoint is:

npx -y oz-assist@latest assist

assist resolves the active partner session when one exists, pulls initial product docs context, maps the current codebase, asks guided questions when intent is missing, and returns selectable option cards. Every option set includes best_for_stack, which lets OZ choose the best path for the detected stack and use case.

Artifact Flow

The workflow writes small JSON artifacts under .oz/assist/runs/<context>/:

1. BRIEF.json from oz-assist assist or oz-assist interview
2. OPTIONS.json from oz-assist assist or oz-assist research
3. DECISIONS.json from oz-assist assist --option-id <id> or oz-assist decide
4. PLAN.json from oz-assist assist --option-id <id> or oz-assist build
5. VERIFICATION.json from oz-assist verify
6. DRIFT.json from oz-assist drift

research, verify, and drift require the OZ dashboard/index API. If the index has no matching docs, the command fails or records a real miss instead of fabricating results.

Telemetry

The CLI and MCP server emit best-effort telemetry to the dashboard so the company view can separate user friction by source:

• CLI commands post to /v1/telemetry/cli.
• MCP tools post to /v1/telemetry/mcp.
• Events include command/tool name, duration, tenant/dev identifiers when provided, library/version, artifact metadata, and friction kind on failures.
• Set OZ_DASHBOARD_URL to point at the live OZ broker API when using a non-default broker.
• Set OZ_TELEMETRY_DISABLED=1 to disable local emission.

Telemetry is fire-and-forget and never blocks the assist workflow when the dashboard is unavailable.

CLI

Customer developers can install OZ Assist with one short command:

npx oz-assist@latest

Partner docs pages and the OZ admin dashboard should use the same command with either a company slug or install URL:

npx oz-assist@latest acme
npx oz-assist@latest https://oz.company.com/i/<install-token>

The wizard asks for an OZ API key or email, creates a key from the email when needed, detects available coding agents, preselects the detected agents, and installs only the integrations the developer keeps selected. With a partner slug or install URL it also resolves that company's install profile and starts a time-bounded integration session. If OZ Assist is already installed, running the command with a partner slug or URL skips reinstall and starts the scoped company integration session directly. Partner telemetry is limited to that active session and stops after end, success, or expiry.

You can also pass the key or email non-interactively:

OZ_API_KEY=<oz-api-key> npx oz-assist@latest acme
npx oz-assist@latest acme --email [email protected]

npm run assist -- --dry-run
npm run assist -- acme --dry-run
npm run assist -- acme --diff
npm run assist -- start acme
npm run assist -- assist
npm run assist -- assist --objective "Integrate payments checkout" --library acme --version 2024-06
npm run assist -- assist --objective "Integrate payments checkout" --library acme --version 2024-06 --option-id best_for_stack
npm run assist -- docs "How should this app authenticate?"
npm run assist -- end acme
npm run assist -- doctor
npm run assist -- help --all
npm run assist -- info
npm run assist -- remove
npm run assist -- interview --objective "Integrate payments checkout" --library acme --version 2024-06
npm run assist -- research --library acme --version 2024-06
npm run assist -- decide --option primary_path --rationale "Matches the checkout flow"
npm run assist -- build
npm run assist -- verify --diff-file ./path/to/diff.txt
npm run assist -- drift --latest-version 2024-09

MCP

npm run assist:mcp

The MCP server exposes:

• oz_assist
• get_library_id
• get_library_docs

oz_assist is the only OZ workflow tool. Pass action to start/end partner sessions, continue the guided solution-engineer flow, select an option, verify a plan/diff, check drift, or inspect status. get_library_id and get_library_docs are general TryOZ public-docs tools and should not be used to manage partner sessions or telemetry.

Supported oz_assist.action values:

• start_session
• continue
• research
• select_option
• build
• verify
• drift
• status
• end_session

Skill

To install the bundled OZ Assist skill into the current repo's Codex skill directory:

npm run assist -- install-skills --target .codex/skills

The skill file stays source-controlled in this package; installation is a copy step for local agent runtimes.