--- title: "Coding agents and Cloud Agent bootstrap" description: "Provider-neutral in-repo contracts for Cursor, Codex, Claude, Grok, and poteto. architecture.mnppi.org is the operating source of truth. HTML email uses @mnppi/email-layout with CID-embedded logos." url: "https://architecture.mnppi.org/delivery/coding-agents/" status: "Current" last_updated: "2026-10-02" --- # Coding agents and Cloud Agent bootstrap **Standard details** - Status: Current - Reviewed: October 1, 2026 - Cadence: Review each quarter - Source: org-standards Every active MNPPI repository must bootstrap for Cloud and remote coding agents without macOS Keychain or home-directory harness installs. **[architecture.mnppi.org](https://architecture.mnppi.org) is the operating source of truth for MNPPI policy.** Coding agents, including poteto, Cursor Cloud Agents, Codex, Claude Code, Grok CLI, and Grok computer-use sessions, must default to these published standards before inventing toolchain, mail, deploy, or bootstrap behavior. This standard is provider-neutral. It applies to those agents when they work in a repository checkout. Workstation harness profiles (rules and skills under the home directory) help local Mac work. They do **not** travel to Cloud or remote VMs. Put operating contracts in the repository. Keep `MNPPI/org-standards` as the Git home of this site. Keep `MNPPI/agent-management` as the Mac installer for local harness profiles. Do not merge those repositories. Do not treat a home-directory harness, a vendor default, or a prior repo habit as a substitute for this site. Pull portable requirements into this standard and into `@mnppi/quality` audits instead of linking Cloud Agents at agent-management. > **Caution — Default to these standards** > > Read this site first. Apply the published rule. Invent a path only when this > site has no rule and the gap is recorded. ## Required in-repo contract Every active product, app, docs, Worker, or automation repository must include: | Artifact | Role | | -------------------------- | ----------------------------------------------------------- | | `AGENTS.md` | Canonical operating handbook for agents | | `.cursor/environment.json` | Declares install command, optional dev terminals, and ports | | `.cursor/install.sh` | Idempotent cold bootstrap that exits 0 on a clean VM | | Toolchain pin | Exact Node (`.nvmrc`) or language-equivalent pin | | Package manager pin | `package.json` `packageManager` when the repo uses Node | | Repomix `context:pack` | Safe focused pack per the quality agent-context rules | Add `.cursor/dev.sh` when the repo has a long-lived local server. Use one canonical `AGENTS.md`. Do not maintain a divergent `CLAUDE.md` as a second instruction set. ## Hybrid install paths | Environment | How secrets load | How install runs | | -------------------- | ------------------------------------------------------- | ------------------------------------------------ | | Mac workstation | Keychain through direnv when the repo uses that pattern | Same install script or documented local commands | | Cloud / remote agent | Runtime secrets such as `MNPPI_PACKAGE_TOKEN` | `.cursor/install.sh` from `environment.json` | Public dependency installs must work without a token. Private `@mnppi` packages need the Cloud secret `MNPPI_PACKAGE_TOKEN` (GitHub Packages read) and an in-repo `.cursor/install.sh`. A repository that depends on `@mnppi/*` without Cloud Agent bootstrap is a hole. Do not vendor those packages as a Packages workaround. Never commit tokens, put them in chat, or store them in `.dev.vars` beyond local development overrides that stay gitignored. Document which CI paths stay tokenless and which local or Cloud paths need secrets. Required quality and pull request jobs stay on `GITHUB_TOKEN` only. Do not add a `PACKAGES_TOKEN` secret there. | Install path | Auth | Companion config | | ------------------------- | --------------------------------------------- | -------------------------- | | GitHub Actions | `GITHUB_TOKEN` plus **Manage Actions access** | Registry scope in `.npmrc` | | Cursor Cloud Agent | `MNPPI_PACKAGE_TOKEN` | `.cursor/install.sh` | | Cloudflare Workers Builds | `NODE_AUTH_TOKEN` | Committed `.npmrc.builds` | **Manage Actions access** does not authenticate Workers Builds. Workers that install `@mnppi/*` need a per-trigger Build secret named `NODE_AUTH_TOKEN` and committed `.npmrc.builds`. See `docs/private-package-distribution.md`. ## What `AGENTS.md` must cover - Hybrid workstation vs Cloud install paths - Toolchain pins and how to bump them. Workers that run `cf` need **Node ≥ 22**. - Tokenless CI vs secrets for private packages or Cloudflare API tokens - Who owns production deploy (normally Cloudflare Workers Builds) - Cloudflare toolchain: `cf` CLI + Vite + `cloudflare.config.ts` for new Vite-ready Workers **with a Worker entry**. Assets-only Astro and repos without BOS stay on labeled transitional Wrangler. See the [whitelist](https://architecture.mnppi.org/delivery/cf-cli-and-cloudflare-config/index.md#transitional-wrangler) and [pilot-proven fences](https://architecture.mnppi.org/delivery/cf-cli-and-cloudflare-config/index.md#pilot-proven-fences) - How to validate a change (`pnpm` scripts or language equivalents). Worker `cf:check` is `cf deploy --dry-run` only when BOS exists; otherwise `wrangler deploy --dry-run` - Discovery rule: `cf cli search` then ` --help`. Do not invent CLI flags - Pointer to Archify for architecture diagrams when diagrams are in scope - When the repository depends on `@mnppi/*`: Cloud Agent bootstrap is required (`.cursor/install.sh` plus `MNPPI_PACKAGE_TOKEN`). Do not vendor those packages. Grant sibling packages such as `@mnppi/email-layout` when the install graph includes them. Workers Builds uses `NODE_AUTH_TOKEN` plus `.npmrc.builds`, not `GITHUB_TOKEN`. - When the repository sends transactional, ops, or notify HTML email: depend on `@mnppi/email-layout` and `BRAND_PRESETS`, CID-embed logos by default, and name that package in `AGENTS.md` so poteto and Cloud Agents do not invent a layout ## HTML email Any transactional, ops, or notify HTML email must use the private package `@mnppi/email-layout` and its `BRAND_PRESETS`. Use `BRAND_PRESETS.mnppi` for `notify.mnppi.org` and other MNPPI ops alerts. Embed logos with CID by default: `getCloudflareLogoAttachment` plus `LOGO_CID`, `logoSrc` as `cid:…`, and the PNG as an inline attachment. Match the `mnppi-org` heartbeat and backup senders. Use remote `logoUrl` only when no embedded PNG is available. Do not default to a remote logo (that prompts clients to “load remote images”). The package lives at `MNPPI/mnppi-org` → `packages/email-layout` and publishes to GitHub Packages as `@mnppi/email-layout`. Follow the canonical README at `MNPPI/mnppi-org` → `packages/email-layout/README.md`. Do not copy that README into this repo or invent a second layout API. Org mail stays on Cloudflare Email Sending only. There is no Resend path. Install and token rules stay in `docs/private-package-distribution.md`. ## Enforcement `@mnppi/quality` and the organization quality audit treat `cloudAgentBootstrap` as a required recommended signal for active software and docs repositories: - `AGENTS.md` present at the repository root - `.cursor/environment.json` present - Install path declared and pointing at an in-repo script Organization-metadata-only repositories may ship a thin `AGENTS.md` without an app environment when they have no installable runtime. ## Diagrams Prefer Archify for architecture, workflow, sequence, dataflow, and lifecycle diagrams. See the [Cloudflare flagship stack](https://architecture.mnppi.org/architecture/cloudflare-flagship-stack/index.md) documentation diagrams section. ## Reference implementation Copy the shape from `MNPPI/packing-checklist`: - `.cursor/environment.json` - `.cursor/install.sh` - `.cursor/README.md` - Root `AGENTS.md` - `.nvmrc` aligned with Workers Builds and CI For a new private repository with `security_baseline` `shared-private` or `custom-equivalent`, Grok or Standards grants the repo **Read** under each private `@mnppi/*` package the workflows install with `GITHUB_TOKEN`. Always grant `@mnppi/quality`. Also grant siblings such as `@mnppi/email-layout`, `@mnppi/quality-ts`, `@mnppi/design-tokens`, and `@mnppi/error-monitor` when the repo or workflow depends on them. Use **Manage Actions access → Add repository** in the signed-in box browser before the first required private quality run. The same UI path applies; the package name is in the URL. GitHub inherit from the source repository covers only the linked repo (`mnppi-org`). It is not org-wide consumer Actions access. Organization **Settings → Packages** default inherit only applies that linked-repo inherit to new packages. GitHub has no public API for the Actions access list. Do not add a `PACKAGES_TOKEN` secret. See the private required-quality standard in `docs/private-required-quality.md`. When the repository is a Worker that installs `@mnppi/*`, preview Builds env must match prod Packages auth. See `docs/private-package-distribution.md`. When a repository depends on `@mnppi/*`, Cloud Agent bootstrap is required: `AGENTS.md`, `.cursor/environment.json`, and `.cursor/install.sh` that reads `MNPPI_PACKAGE_TOKEN`. Do not vendor `@mnppi/*` sources to skip Packages auth. ## Remote computer-use agents For Grok online, Grok Bot, or any computer-use agent with a GitHub checkout: 1. Read `AGENTS.md` first, then this site. Default to these standards before inventing shop defaults. 2. Run the documented install from `.cursor/environment.json`. 3. Do not invent secrets or Docker sandboxes. 4. Prefer the designated GitHub runner queue for CI. Do not create substitute runners or containers to bypass that queue. ## Forbidden - Docker or a `.devcontainer` as the default Cloud Agent sandbox - Substitute VMs or runners that bypass the designated self-hosted runner queue - Fake `_mcp._agents` or `_a2a._agents` DNS without live services - Committing secrets, generated Repomix packs, or Keychain material - Assuming `~/.cursor/skills` or Keychain exist on a remote VM - Invented `cf` or Wrangler flags. Use `cf cli search` and documented commands - Wrangler-as-`cf` shims, aliases, or scripts - Mass fleet `cf migrate` outside the accepted pilots - Dropping FedRAMP D1 UUID pins during migrate or “cleanup” - Inventing policy, mail, or bootstrap defaults that this site already states - Vendoring `@mnppi/*` packages as a GitHub Packages workaround - One-off HTML email shells or Resend templates. Use `@mnppi/email-layout` and `BRAND_PRESETS`. - Defaulting HTML email logos to a remote `logoUrl`. CID-embed via `getCloudflareLogoAttachment` and `LOGO_CID`. - Resend or any mail provider other than Cloudflare Email Sending ## Acceptance gate A repository is Cloud Agent ready when: - A cold Cloud or remote agent can install without human Keychain access. - `AGENTS.md` and `.cursor/environment.json` are present and agree. - `.cursor/install.sh` exits 0 on a clean VM. - `context:pack` works and stays gitignored. - Cursor Environment Builds, when enabled, run the same in-repo scripts. - No Docker sandbox was added only for agents. - If the repository depends on `@mnppi/*`, Cloud bootstrap installs with `MNPPI_PACKAGE_TOKEN` and the registry. It does not vendor those packages. - If the repository sends transactional, ops, or notify HTML email, the app depends on `@mnppi/email-layout` and `BRAND_PRESETS`, CID-embeds logos by default, and `AGENTS.md` names that package.