# Nexus Capital OS Type 3 Partner — AI Agent Runbook

Version: 2.0  
Canonical manual: https://capital-demo.rwa.nexus/manual?locale=en  
AI Agent bootstrap: https://capital-demo.rwa.nexus/manual/agent-bootstrap.en.md  
Machine-readable menu: https://capital-demo.rwa.nexus/manual/agent-menu.json

## Purpose

Use this runbook to create and maintain a private Nexus Capital OS instance from the authorized `reyerchu/capital-demo` partner repository. The partner owns its fork, profile, extensions, infrastructure and data. Shared Nexus Capital OS modules remain traceable to upstream versions.

This document is an operating contract. It does not prove that every repository revision is release-ready.

## Task menu and state machine

Begin every new engagement with read-only `T0`, then select exactly one task that matches the user's explicit request:

| ID | Task | Primary output |
|---|---|---|
| `T0` | Inspect & Readiness | readiness, inventory, blockers |
| `T1` | Fork & Bootstrap | remotes, baseline, partner workspace |
| `T2` | Compose Modules | composition lock and dependency report |
| `T3` | Customize Safely | profile/workflow/form/extension and tests |
| `T4` | Build & Certify | image digest, tests, release evidence |
| `T5` | Install / Deploy | healthy release and rollback point |
| `T6` | Operate & Recover | backup, verified restore, monitoring |
| `T7` | Upgrade Modules | scoped upgrade PR and migration/test plan |
| `T8` | Report / Contribute | sanitized issue, security report, or PR |
| `T9` | Audit / Rollback | audit or restored-release evidence |

Every task follows:

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

Repository writes, external messages, cloud changes, deployments, DNS, migrations, data, or service mutations require an exact target and authorization at `AUTHORIZE`. Return `WAITING_AUTHORIZATION` when authority is missing.

## Non-negotiable rules

1. Read all applicable `AGENTS.md` and `CLAUDE.md` files before acting.
2. Start with read-only discovery. Do not mutate infrastructure during discovery.
3. Never copy production customer data into a demo, fixture, test or partner environment.
4. Never commit credentials, tokens, cookies, private keys, `.env` files or database dumps.
5. Never invent a missing command, module version, artifact, digest, credential or test result.
6. Never deploy or run a database migration without explicit authorization naming the host and environment.
7. Do not modify shared modules for partner-only behavior when configuration or an extension can implement it.
8. Do not claim an upgrade succeeded without tests, health checks and recorded evidence.

## Repository model

Expected remotes:

```text
origin    partner-owned private fork
upstream  authorized reyerchu/capital-demo repository
```

Expected customization layers:

```text
partner/profile.json                    branding, domain, locale, and safe settings
partner/locks/composition.lock.json     exact module versions, digests, and dependencies
partner/extensions/*                    private workflows, reports, and integrations
source/modules/*                        shared upstream product modules
```

The exact file names may evolve. Use repository documentation as authority; do not create look-alike paths merely to pass this checklist.

## T0 / Phase 1 — Read-only discovery

Report:

- repository URL, branch, commit and working-tree status;
- applicable instruction files;
- package manager and supported runtime versions;
- module manifest and composition locations;
- enabled module IDs, versions and digests;
- build, test, composition-validation and deployment commands actually defined by the repository;
- database, file storage, provider and external-service dependencies;
- target environment, if explicitly authorized;
- missing information and risks.

Do not print secret values. Report only variable names and whether they are set.

## T0 / Phase 2 — Readiness Gate

Stop and report `NOT_READY` if any required condition fails:

- a documented partner workspace and supported build command exist;
- each enabled module has ID, version, dependencies and integrity metadata;
- profile and composition validate against their repository schemas;
- the repository has no detected secrets or production customer data;
- supported clean-install tests exist;
- tenant isolation, authentication and authorization tests exist;
- the release defines migration, backup/restore and rollback behavior;
- the target host and environment are unambiguous before deployment.

Never create fake files or bypass checks to convert `NOT_READY` into `READY`.

## T1 — Fork and branch

1. Fork the complete `reyerchu/capital-demo` repository; this fork is the only long-lived development and maintenance tree.
2. Confirm `origin` is the partner-owned private fork.
3. Confirm `upstream` is the approved Nexus Capital OS repository and run `./caas --format json fork-check`.
4. Fetch without merging.
5. Record the upstream baseline commit.
6. Create a feature branch. Do not develop directly on protected `main`.
7. Keep `dist/workspace`, generated files, and secrets out of Git.

Recommended partner workflow:

```text
upstream/main
    -> partner upgrade branch
    -> automated compatibility and affected-flow tests
    -> reviewed PR into partner/main
    -> immutable image build
    -> partner-controlled deployment
```

## T2–T3 — Compose and configure the partner instance

Prefer changes in this order:

1. configuration;
2. workflow or form definition;
3. partner extension;
4. shared module change only when reusable or unavoidable.

For every requested feature, identify:

- owning module;
- affected roles and permissions;
- affected routes, APIs, forms and jobs;
- database and file-storage impact;
- required provider or external dependency;
- unit, contract, integration and E2E coverage.

If shared module code must change:

1. isolate the change to the owning module;
2. add regression tests;
3. open an upstream-candidate PR;
4. after upstream publishes a fixed version, upgrade and remove the local patch.

## T4 — Build and validate

Use only commands documented in the checked-out revision. Required outcomes:

```bash
./caas test
./caas workspace
./caas build --tag capital-distribution:<unique-tag>
```

The current `workspace` command certifies only the repository's shipped 22-module composition (all modules except `billing`). A different partner selection returns `WORKSPACE_PROFILE_SELECTION_NOT_YET_SUPPORTED`; never bypass that gate with an unverified manual assembly.

Commit partner customization in the private fork under `partner/extensions/*`. Every extension addition or replacement is hash-bound; if upstream changes the same file, workspace creation stops with a conflict. Build extension images with `capital-distribution:private-<unique-tag>`; they are labelled `vendor-certified=false`.

- profile and composition validation pass;
- dependency graph has no unresolved or circular requirements;
- lint/type/unit/contract/integration checks pass as required by the repository;
- affected role/page/link/API/form E2E tests pass;
- tenant isolation and authorization regression tests pass;
- fresh database installation passes;
- upgrade from the oldest supported source version passes;
- Docker/Compose configuration validates;
- image is identified by immutable digest;
- SBOM/provenance are produced when supported.

Do not call a build reproducible unless the repository's reproducibility check passes.

## Hosting guidance — optional, not prescriptive

The partner chooses its own hosting provider and remains responsible for its account, network, availability and cost controls. Do not require GCP or AWS. Use the repository's supported Docker/Compose interface so the same application can run on either cloud or a suitable Linux host.

Suggested starting points, subject to measurement:

| Use | Baseline | Example services |
|---|---|---|
| Pilot | 2 vCPU, 8 GB RAM, 30 GB boot, 50–100 GB SSD data | GCP Compute Engine or AWS EC2 with Docker Compose |
| Small production | 4 vCPU, 16 GB RAM, monitored SSD capacity | VM plus optional Cloud SQL/RDS and GCS/S3 |
| Existing platform team | Capacity based on load tests | The partner's supported container platform; Kubernetes is optional |

Security baseline:

- expose only HTTP/HTTPS;
- keep PostgreSQL, Redis and object storage private;
- prefer IAP, AWS Systems Manager Session Manager or an approved bastion over public SSH;
- use cloud secret management or protected host secrets, never Git;
- keep encrypted backups outside the application host and verify restore;
- collect health, resource, application and audit signals without logging secrets.

## T5 — Deployment plan

Before any deployment, produce a written plan containing:

- exact target host, cloud/project/account and environment;
- current and target image digests;
- enabled module versions;
- environment-variable names and secret-storage locations, never values;
- database and object-storage endpoints by logical name;
- backup and verified restore point;
- migration order and reversibility classification;
- health, smoke, role and business-flow checks;
- canary and traffic-switch procedure;
- rollback conditions and commands supported by the repository;
- responsible approver.

Wait for explicit deployment authorization if it has not already been given for that named target.

## T5 — Safe deployment

1. Verify target identity again.
2. Back up database, objects and configuration.
3. Verify restore against an isolated target when required by the release policy.
4. Pull by immutable digest.
5. Run preflight and compatibility checks.
6. Apply only approved migrations.
7. Start the canary or replacement service without deleting the previous release.
8. Run health, authentication, authorization, tenant-isolation and affected-flow tests.
9. Switch traffic only after checks pass.
10. Retain the previous image and restore point for the defined observation window.

Never use destructive cleanup flags against a shared Compose project unless the repository runbook explicitly proves the target set.

## T6–T7 — Operations and future module maintenance

For every upstream release notice:

1. fetch upstream and check out the exact candidate commit in a separate worktree;
2. run `./caas upstream-status --target-checkout <path> --expected-target-commit <40-hex-commit>` to map that commit to module/version changes;
3. run `./caas fork-debt` against clean, commit-pinned accepted-baseline and target checkouts; `partner/**` remains partner-owned, while shared bytes matching neither side require review;
4. compare installed and available module versions;
5. read release notes, compatibility range, security impact and migration classification;
6. create an upgrade branch or automated upgrade PR;
7. update only the selected module, lockfile and required dependencies;
8. three-way merge source updates in a partner fork—never blindly overwrite partner code;
9. run affected tests and full composition gates required by policy;
10. rehearse backup/restore and migration for data-changing releases;
11. deploy by canary and record the new digest;
12. close the upgrade with evidence.

If the partner modified the same upstream code, report a conflict. No tool can guarantee a conflict-free upgrade when both sides changed the same lines or contract.

## T8 — Bug reports and upstream contribution

First run `./caas contribute-plan --module <id> --kind bugfix|feature|security --out <path>` to create the contribution contract. It writes a local plan and does not submit an issue or pull request. A `security` plan is forced onto the private-disclosure path.

Before filing an issue:

1. search existing issues and release notes;
2. confirm the affected module, installed version and whether the problem also occurs without partner extensions;
3. create the smallest safe reproduction using synthetic data;
4. remove credentials, personal data, private domains and proprietary code from all evidence.

A normal bug issue should include:

- affected module and exact version/digest;
- severity and business impact;
- user role, route/API and workflow stage;
- deterministic reproduction steps;
- expected and actual behavior;
- sanitized logs, screenshots or request IDs;
- regression status and known workaround;
- hosting/runtime facts only when relevant.

Do not open a public issue for a suspected vulnerability, tenant escape, authentication bypass, secret exposure or exploitable data leak. Use the upstream repository's private security reporting path and disclose only to authorized maintainers.

An upstream PR must include:

- problem statement and affected module;
- minimal scoped implementation;
- tests demonstrating the previous failure and new behavior;
- compatibility and migration impact;
- security and tenant-isolation impact;
- changelog entry;
- confirmation that partner secrets, branding and proprietary data are absent.

Keep partner-only features in private extensions unless both parties decide they belong in the shared product.

Recommended branch and PR flow:

```text
issue
 -> fix/<module>-<short-description>
 -> failing regression test
 -> minimal module-scoped fix
 -> compatibility/migration/security notes
 -> upstream PR
 -> reviewed merge
 -> new module version
 -> partner upgrade PR
 -> remove temporary local patch
```

Do not mix refactors, partner branding and an upstream bug fix in the same PR.

## T9 and required completion report

Use `./caas evidence-verify --evidence <path> --require-current-repo` to bind evidence to the current commit and composition. Before any rollback, generate a plan with `./caas rollback-plan --evidence <path> --target-id <id> --environment <env> --previous-image <immutable-image> --migration-mode <mode> --out <path>`. An incompatible migration requires an explicit rollback point, and remote execution still requires authorization.

Return:

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

Do not use `DEPLOYED` when only a local build or staging test completed.
