Coding agents and Cloud Agent bootstrap

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 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.

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 and 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 <command> --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 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:

Read AGENTS.md first, then this site. Default to these standards before inventing shop defaults.
Run the documented install from .cursor/environment.json.
Do not invent secrets or Docker sandboxes.
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.