# Bootstrap and state scripts

All scripts in this directory use only the Python standard library so they work before the project toolchain is installed.

```bash
python scripts/validate_pack.py
python scripts/next_packet.py
python scripts/render_luna_context.py
python scripts/update_state.py WP-000 in_progress
python scripts/create_manifest.py
python scripts/promotion_preflight.py --env-file <operator-owned-production.env> --phase predeploy --verify-registry
```

`validate_pack.py` checks packet dependencies/references, catalog identities and cross-references, contract JSON syntax, forbidden generic tool patterns, obvious secrets, and an optional checksum manifest.

`render_luna_context.py` intentionally fails rather than silently truncating authoritative files. Narrow a packet's `read` list if a future context bundle becomes too large.

`update_state.py` enforces ordinary packet transitions and synchronizes a small machine-state section in `CURRENT_STATE.md`. Significant implementation detail still belongs in the packet evidence and human-readable state sections.

`promotion_preflight.py` is a read-only, fail-closed production gate. It checks
operator-supplied paths, secret-file mode/ownership, immutable Compose image
references, Docker networks, DNS expectations, and TCP reachability without
printing secret values. It must be run with an external production env file;
the repository `.env.example` is intentionally not sufficient.

`verify_demo_token_runtime.py` is a second, live-Docker read-only gate for the
Fleet Ops demo token. Run it on Tower immediately before minting or revoking:

```sh
python scripts/verify_demo_token_runtime.py \
  --router-container itworx-mcp-hub-dataplane-router-1 \
  --expected-host-file /srv/example/appdata/itworx-mcp-hub/config/demo-token-revocations.json
```

It rejects a missing env-file value, a repository example fallback, a wrong
mount source, a writable mount, or any file mode other than `0600`.

`verify_demo_token_flow.py` is the live functional proof. It mints a one-hour
demo token in memory, calls the fixed Fleet Ops tool, atomically revokes that
token even when the valid call fails, then requires a `401` for the revoked
call. It prints only HTTP/content metadata, never the token or response body:

```sh
python -m scripts.verify_demo_token_flow \
  --endpoint https://mcp.example.test/mcp/mobilityops/prod \
  --key-file /srv/example/appdata/itworx-mcp-hub/secrets/demo_token_signing_key \
  --revocations-file /srv/example/appdata/itworx-mcp-hub/config/demo-token-revocations.json
```

On Tower, use the optional container profile instead of the host Python
runtime (which is intentionally not a project dependency environment):

```sh
docker compose --env-file /srv/example/appdata/itworx-mcp-hub/config/production.env.pending \
  -f infrastructure/compose/docker-compose.yml \
  -f infrastructure/compose/docker-compose.prod.yml \
  run --rm --no-deps operator-tools \
  --endpoint http://dataplane-router:8080/mcp/mobilityops/prod \
  --key-file /run/secrets/demo_token_signing_key \
  --revocations-file /etc/itworx/demo-token-revocations.json
```

## Codex machine clients

The production Codex path is documented in
`docs/04-mcp/CODEX_INTEGRATION.md`. Its bounded operator tools are:

- `new_codex_credential.ps1`: create a CSPRNG credential in a current-user-only file;
- `authentik_provision_mcp_service_account.py`: idempotent Authentik shell payload;
- `provision_machine_client.py`: activate the exact Authentik subject and project binding;
- `install_codex_mcp.ps1`: install the secret-free Codex stdio configuration;
- `mcp_stdio_bridge.py`: retrieve/refresh M2M tokens and forward only allowlisted MCP methods.