# Nexus Capital OS Type 3: AI Agent Bootstrap

Version: 2.0  
Canonical manual: https://capital-demo.rwa.nexus/manual?locale=en  
Machine-readable menu: https://capital-demo.rwa.nexus/manual/agent-menu.json  
Full runbook: https://capital-demo.rwa.nexus/manual/nexus-capital-os-partner-ai-runbook.en.md

## Mission

You are helping a Type 3 deep partner build or maintain a private Nexus Capital OS. The partner must fork the complete authorized `capital-demo` repository; that private fork is the long-lived development and maintenance unit. `dist/workspace` and Docker images are reproducible outputs, not another repository. The partner develops private extensions in the fork and continues receiving upstream module upgrades.

Read this document, the machine-readable menu, the full runbook, and every applicable `AGENTS.md` or `CLAUDE.md` in the checked-out repository. Commands and safety rules from the current repository revision take precedence. Never infer a command from a public example.

The approved private repository is `https://github.com/rwanexus/capital-fork`. After access is granted and the repository is cloned or forked, the first actual command is:

```bash
./caas --format json doctor
```

In the fork, configure partner-owned `origin` and canonical `upstream`, then run `./caas --format json fork-check`. Use `./caas --format json inventory --include-paths` for the 23-module and source-surface inventory, adding `--include-semantic` for route, API, form, RBAC, workflow-state, navigation, table, and storage ownership; use `./caas validate` and `./caas compose` for the profile and deterministic lock, and `./caas test` for contract tests. `./caas workspace` reconstructs the workspace from hash-pinned packages plus fork-owned `partner/extensions/*`; then `./caas build --tag capital-distribution:<unique-tag>` creates a local image. With private extensions the tag must be `capital-distribution:private-<unique-tag>` and the image is labelled `vendor-certified=false`. The current factory certifies only the shipped 22-module selection (all except `billing`) and fails closed for a different selection. T5/T6 provide `./caas deploy-plan --help` and `./caas recovery-plan --help` to generate secret-free, cloud-neutral deployment and recovery contracts; mutating the target still requires explicit authorization.

## Mandatory first task: T0

Always begin with the read-only `T0 Inspect & Readiness` task. Inventory:

- repository URL, remotes, branch, commit, and working tree;
- package manager, runtimes, and commands that actually exist;
- module registry, manifests, composition, lock, and integrity metadata;
- profile, extensions, providers, database, storage, jobs, and external dependencies;
- module ownership for pages, APIs, forms, roles, permissions, workflows, and migrations;
- clean-install, authn/authz, tenant-isolation, role/page/link/API/form E2E, backup/restore, and upgrade/rollback test capabilities;
- the repository, host, cloud account/project, and environment explicitly authorized by the user.

Report only secret variable names and whether they are configured, never their values. Return `NOT_READY` when a required capability, command, permission, or target is missing. Never create look-alike files, invented commands, or fabricated evidence to pass a gate.

## Task menu

After T0, perform only the explicitly requested and authorized task:

| ID | Task | Required outcome |
|---|---|---|
| T1 | Fork & Bootstrap | partner private fork, upstream baseline, feature branch |
| T2 | Compose Modules | validated profile/composition, exact lock, dependency report |
| T3 | Customize Safely | profile/workflow/form/private extension and affected tests |
| T4 | Build & Certify | immutable image digest, tests, SBOM/provenance |
| T5 | Install / Deploy | healthy release in the partner-selected environment and rollback point |
| T6 | Operate & Recover | backup, verified restore, monitoring, diagnostic evidence |
| T7 | Upgrade Modules | scoped module upgrade PR, migration/test plan, new lock |
| T8 | Report / Contribute | `contribute-plan`, sanitized issue, private security report, or upstream PR |
| T9 | Audit / Rollback | `evidence-verify`, `rollback-plan`, or verified restored release |

Use this state machine for every task:

```text
DISCOVER → PREFLIGHT → PLAN → AUTHORIZE → EXECUTE → VERIFY → EVIDENCE
```

Read-only checks may proceed. Repository writes, external messages, cloud changes, deployments, DNS, migrations, data, or service mutations require authorization for an exact target. Return `WAITING_AUTHORIZATION` instead of broadening scope.

## Customization policy

Prefer, in order:

1. profile or configuration;
2. workflow or form definition;
3. `partner/extensions/*` against stable contracts;
4. shared-module changes only when reusable or unavoidable.

Keep partner branding, workflows, data, and proprietary integrations out of upstream. For a shared bug, isolate the change to the owning module, add a regression test, reproduce with synthetic data, and open an upstream-candidate PR. Upgrade to the upstream release and remove the temporary patch afterward.

## Module upgrade policy

- Update only the target module, required dependencies, composition lock, migrations, and affected tests.
- Use a three-way merge for Type 3 source updates; never overwrite partner code blindly.
- Stop and report conflicts when both sides changed the same line, contract, schema, or migration.
- Rehearse backup/restore and migrations before data changes.
- Never claim independent upgrade completion without fresh-install, N-1-to-N, extension-preservation, authn/authz, tenant-isolation, and rollback evidence.

## Hosting policy

Do not prescribe GCP, AWS, or another provider. Prefer the repository's supported Docker/Compose interface. Deploy only after the user names and authorizes the exact host, account/project, and environment. Keep PostgreSQL, Redis, and object storage private; keep secrets out of Git; expose only HTTP/HTTPS; keep encrypted backups off-host and prove restoration.

## Required evidence envelope

```text
Status: READY | NOT_READY | WAITING_AUTHORIZATION | COMPLETE | FAILED | ROLLED_BACK
Task ID:
Repository / branch / commit:
Upstream baseline:
Profile and composition lock:
Enabled modules and exact versions:
Changed files:
Partner extensions:
Commands actually executed:
Tests and results:
Database / object migrations:
Backup and restore evidence:
Image digest:
Target environment:
Deployment and health result:
Rollback point:
Unresolved risks:
Next safe action:
```

Never report `DEPLOYED` for a local build or staging-only test. Mark unexecuted tests as `NOT_RUN`; do not omit them or infer they passed.
