Multiplayer agent harness for work.
Support customizable source forks alongside package deployments (#1169)
Regan Bella811cc4149f4
diff --git a/.codex/skills/update-qm/SKILL.md b/.codex/skills/update-qm/SKILL.mdindex f8fc4d018..d4d9821b4 100644--- a/.codex/skills/update-qm/SKILL.md+++ b/.codex/skills/update-qm/SKILL.md@@ -1,37 +1,41 @@---name: update-qm-description: Update a private qm fork by merging upstream qm into it and opening a sync PR. Use when asked to "update qm", "sync from upstream", "pull in the latest qm".+description: Update a QM source fork by merging upstream, or upgrade a package deployment dependency, and open a PR. Use when asked to "update qm", "sync from upstream", "pull in the latest qm".---# update-qm-An organization customizes qm from a private fork: a standalone private repository whose-history begins as a clone of qm, with everything organization-specific confined to-`deploy/layers/<org>/` and the rest of the tree identical to upstream. That rest is what-this skill means by core: every file outside the organization's layer directory,-including the plugins, the CLI, the docs, and CI, not just the runtime under `src/`.-This skill keeps a private fork current. It merges upstream qm in and opens the-resulting sync PR.--See [`deploy/layers/README.md`](../../../deploy/layers/README.md) for the layer boundary,-and the `upstream-pr` skill for sending changes the other direction.--## Check that there is anything to sync--```bash-git remote -v-```--If `origin` is `yc-software/qm`, stop: you are in upstream qm, and a repository-cannot merge from itself. Never merge an organization's private fork into qm.--Otherwise proceed. Judge by where `origin` points, not by the repository's name.--If the clone has no `upstream` remote, add it:--```bash-git remote add upstream [email protected]:yc-software/qm-```+Determine whether this is a source fork or a package deployment before choosing the+update procedure. Source forks may intentionally change core; preserve those changes.+Contributing them upstream is optional.++## Identify the checkout++Run `git remote -v` and inspect the files and ancestry. If `origin` is `yc-software/qm`,+this is upstream itself, not a downstream sync target. A different origin alone does+not prove a source fork. A source fork has the QM source tree and shared upstream+history; a package deployment has a deployment config and a pinned `@yc-software/qm`+dependency. In a source fork with nested deployment directories, update source unless+the request specifically targets a nested package pin.++For a package deployment, work on a topic branch and install the requested release with+`npm install --save-exact @yc-software/qm@<version>`. If no version is specified, resolve+the current published release first. Review the package and lockfile diff, contract+changes, and image overrides that could keep workloads on older images. Package updates+do not refresh generated runbooks, skills, or vendored Terraform: compare the release's+scaffold in a separate temporary directory and reconcile required changes without+reinitializing or overwriting the existing deployment. Run the installed CLI's `check`,+`doctor`, and `plan`, then open a PR in the deployment repository. Deploy only within+the user's requested scope, following its deployment runbook and live checks. Do not+add an upstream source remote or merge source into a package deployment.++For a source fork, check the `upstream` remote points to `yc-software/qm`; if absent, add+`git remote add upstream [email protected]:yc-software/qm`. Confirm shared history before+merging. Never merge downstream history into upstream. Use `--repo` on every `gh`+command. Inspect the actual default branch; the examples below assume `main` and must+be adapted if the fork deliberately uses another name. If a mirror-seeded repository+has a stale feature branch as its default, identify the intended base before syncing;+do not silently merge into the stale branch or delete existing refs.## Merge, never rebase@@ -42,7 +46,7 @@ upstream rewrites those commits, so always merge.git switch maingit pull --ff-only origin maingit fetch upstream-git switch -c sync-upstream-<yyyy-mm-dd>+git switch -c codex/sync-upstream-<yyyy-mm-dd>git log --oneline main..upstream/maingit merge upstream/main```@@ -53,35 +57,28 @@ PR.## Resolving conflicts-A merge conflict needs both histories to change the same path, and upstream has no files-under `deploy/layers/<org>/`, so an organization's layer cannot conflict with a sync.-Upstream changing the layer contract does not conflict either; it surfaces as a `qm check`-failure, covered below. Every conflict in a sync therefore means the private fork edited a-file that exists in upstream qm, which the layer boundary exists to prevent. For each such-file, decide which happened:--- The edit is organization-specific and should never have been in core. Take upstream's- side, then move the customization into `deploy/layers/<org>/`.-- The edit belongs in core qm for everyone. Resolve in whichever direction keeps the tree- working, then use the `upstream-pr` skill to send it to qm so the next sync stops- conflicting on it.+Read both sides and the local commits that explain the customization. Preserve+intentional local behavior while integrating upstream fixes; a core conflict is expected+maintenance, not a policy violation. Keep deployment data in the layer or separate+private deployment repository where practical. Do not discard a core modification just+because it is organization-specific or insist it be contributed upstream.-List these files in the PR description either way. A private fork that accumulates core edits-gets more expensive to sync each time, and the sync PR is where that cost should be-visible.+Document conflicts, resolutions, and remaining divergence in the sync PR. When intent+cannot be recovered from code, tests, or history, ask the operator before choosing a+behavior. Review inherited CI and publishing changes for the fork's own accounts and+registries rather than enabling upstream workflows blindly.## Verify before opening the PR-A sync changes the runtime, the CLI, and possibly the deployment contract at once, so run-everything. The root suite does not cover the CLI, and the CLI is where a contract change-lands:+Determine affected tests from the merged range and conflict resolutions. Run those+locally plus typecheck and lint; include CLI tests for CLI or deployment-contract changes.+Use the full local suite only when the affected scope cannot be determined; otherwise+let CI run it. Install the locked dependencies first:```bash-npm install+npm cinpm run typechecknpm run lint-npm test-npm --prefix cli test```A sync can raise the deployment contract major, and the CLI rejects a layer config written@@ -92,14 +89,18 @@ work in a source checkout; the workspace symlink points at `cli/`, which is unbunode cli/bin/qm.ts check --config deploy/layers/<org>/qm.config.jsonc```-If that reports an unsupported contract major, updating the layer config to the new shape-is part of this sync.+For deployments outside the checkout, substitute their config paths. If a config reports+an unsupported contract major, adapting it is part of the sync. Verify non-trivial behavior+changes in a live dev instance before opening the PR, per AGENTS.md. Production service+builds must use `--build-from` against this checkout (or deliberately published custom+images); merging source does not update published runtime images. See the README source+deployment procedure.## Open the PR```bash-git push -u origin sync-upstream-<yyyy-mm-dd>-gh pr create --repo <private-fork> --base main \+git push -u origin codex/sync-upstream-<yyyy-mm-dd>+gh pr create --repo <source-fork> --base main \--title "Sync upstream qm through <short-sha>" \--body-file .generated/sync-body.md```@@ -113,19 +114,26 @@ The description should state the upstream commit range merged, any file outside`deploy/layers/` that conflicted and how it was resolved, and the results of the checksabove.+When authorized to land a source-sync PR, preserve the upstream ancestry with a merge+commit (`gh pr merge --repo <source-fork> <pr> --merge`) or an ancestry-preserving+fast-forward. Never squash or rebase a source-sync PR, even if the repository's usual+shipping workflow uses squash: that loses the upstream merge and causes later syncs to+revisit already-integrated history. If repository settings prohibit merge commits,+resolve that policy before landing; do not fall back to squash. Package dependency PRs+can follow the deployment repository's ordinary merge policy.+If the private fork deploys from `main`, merging this PR ships upstream's changes to production,so merge when someone can watch it.-A private fork runs upstream's CI workflows in the organization's own account. A sync that+A source fork runs its enabled CI workflows in its own account. A sync thatadds or changes CI changes what runs on the next PR, and workflows that need secrets thefork never received will fail until those are supplied.## Never do these-- `git push --mirror` to a private fork. It deletes refs the destination has and the- source does not, discarding the organization's own branches, and into an empty- repository it copies every upstream branch, leaving GitHub to pick the default among- them. Seed a fork by pushing `main` alone, as the README shows.+- `git push --mirror` to seed or update a source fork. It copies unrelated branches and+ tags, leaves initial default-branch selection implicit, and can delete destination-only+ refs. Seed only `main` and explicitly set the default branch as the README shows.- Pushing a branch whose history contains organization commits to upstream. The`upstream-pr` skill pushes upstream only from branches cut fresh from `upstream/main`and scrubbed.diff --git a/.codex/skills/update-qm/agents/openai.yaml b/.codex/skills/update-qm/agents/openai.yamlindex ae7efe08d..4996064ef 100644--- a/.codex/skills/update-qm/agents/openai.yaml+++ b/.codex/skills/update-qm/agents/openai.yaml@@ -1,4 +1,4 @@interface:display_name: "Update QM"- short_description: "Merge upstream qm into this private fork"- default_prompt: "Use $update-qm to sync this private fork with upstream qm and open the sync PR."+ short_description: "Update a QM source fork or package deployment"+ default_prompt: "Use $update-qm to update this QM source fork or package deployment and open a PR."diff --git a/.codex/skills/upstream-pr/SKILL.md b/.codex/skills/upstream-pr/SKILL.mdindex 017136673..2bb34d3bc 100644--- a/.codex/skills/upstream-pr/SKILL.md+++ b/.codex/skills/upstream-pr/SKILL.md@@ -1,16 +1,15 @@---name: upstream-pr-description: Send a change to upstream qm without leaking organization-specific context. Use when asked to "upstream this", "open a PR against qm", "contribute this back", or when a fix made in a private fork belongs in core qm.+description: Send a change to upstream qm without leaking organization-specific context. Use when asked to "upstream this", "open a PR against qm", "contribute this back", or when explicitly asked to contribute a downstream change.---# upstream-pr-An organization customizes qm from a private fork: a standalone private repository in-which everything organization-specific lives under `deploy/layers/<org>/` and the rest-of the tree stays identical to upstream. That rest is what this skill means by core:-every file outside the organization's layer directory, including the plugins, the CLI,-the docs, and CI, not just the runtime under `src/`. A private fork's working tree-therefore holds two kinds of material at once, and only one of them may travel upstream.+Source forks may change core freely. This skill applies only when an upstream+contribution is requested; maintaining a local change does not require contributing it.+Keep private deployment material in `deploy/layers/<org>/` in a private source fork or+in a separate private deployment repository for public source. Core means the runtime,+plugins, CLI, docs, and CI, and may also contain private details that must be scrubbed.Upstream qm is shared with organizations other than yours, and anything pushed there ispermanent: it stays reachable by SHA in every clone and fork even after a deleted branch or@@ -21,7 +20,7 @@ See [`deploy/layers/README.md`](../../../deploy/layers/README.md) for the bounda## Where the branch will go-`git remote -v` tells you which of three situations you are in. This decides the push+`git remote -v`, the source tree, and repository metadata identify the situation. This decides the pushtarget only; the scrub steps below run in every case.- `origin` is `yc-software/qm`: you are in upstream qm. Push the branch to `origin`@@ -29,20 +28,23 @@ target only; the scrub steps below run in every case.- `origin` is a GitHub fork of qm, meaning a repository created with GitHub's forkfeature and living inside qm's fork network: push to `origin` and open a normalcross-repo PR.-- `origin` is anything else, including a repository with no remotes: treat it as a- private fork. Assume the working tree holds organization material even if+- A standalone source fork: assume it may hold private material even if`deploy/layers/` looks empty, and read "Pushing from a private fork" below.+- A package deployment or unrelated repository: prepare the contribution in a separate+ clean upstream checkout; never push its history to upstream.Judge by where `origin` points, not by the repository's name. A repository named-`<org>/qm-<something>` in the same GitHub organization as the source is still a private-fork.+`<org>/qm-<something>` in the same GitHub organization as the source may still be a+separate downstream repository.## Decide whether the change belongs upstreamAsk what the change would mean to an organization that is not yours. It belongs upstreamwhen it is a fix or capability in core qm that any deployment would want. It does notbelong upstream when it only makes sense given how your organization is set up: its tools,-its vocabulary, its providers, its process. That change belongs in `deploy/layers/<org>/`.+its vocabulary, its providers, its process. Keep that change downstream: deployment+material belongs in the layer or private deployment repository, while source behavior+may remain a local core modification.A change that is generic in substance but written against org-specific fixtures needs itsfixtures rewritten first. Model them on the account-neutral fixtures under `deploy/stacks/`@@ -61,6 +63,9 @@ nothing:git status --porcelain```+Use `upstream` below for the verified upstream remote; in an upstream checkout use+`origin` instead throughout these commands and the history checks.+Then:```bash@@ -104,8 +109,8 @@ organization's layer directory. The shared `deploy/layers/README.md` is core andchange, which is why the pattern matches only paths inside an organization'ssubdirectory.-**2. No organization identifiers in content, messages, or authorship.** Build the term list-by reading your own layer: `qm.config.jsonc` has the org slug and public URL host,+**2. No private organization identifiers in content, messages, or authorship.** Build the+term list from the private deployment and local core changes, wherever they live: `qm.config.jsonc` has the org slug and public URL host,`.env.example` has the computed secret names, `.env` has the secret values,`slack-app-manifest.yml` has workspace and app names, `infra/terraform.tfvars` has cloudaccount and repository coordinates, and `sandbox/` has internal tool and system names. Add@@ -182,8 +187,9 @@ same reason, pass `--repo` to every `gh` command you run in a private fork: with`gh pr edit 1` can silently overwrite PR #1 of the source repository. If that happens, theprior body is recoverable through the GraphQL `userContentEdits` field.-After the PR merges, do not also commit the change to the private fork. It arrives through the-next `update-qm` sync, and committing it in both places guarantees a conflict.+After the PR merges, bring it downstream through `update-qm`. Preserve any existing local+implementation while reconciling it with the merged version; do not blindly apply the+patch again.## If something leakeddiff --git a/AGENTS.md b/AGENTS.mdindex 1c890a409..a415a20b4 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -73,31 +73,32 @@ Two habits that keep task-focused changes from scarring the rest of the repo:and then show the after state (before/after for changes to something that existed),rendered against realistic data.-## Private forks+## Deployment repositories and source forks-Organizations run qm from private forks of this repository. A private fork is a-standalone private repository whose history begins as a clone of qm. Everything-organization-specific is confined to `deploy/layers/<org>/`, and every file outside-that directory, which these rules call core, stays byte-identical to upstream. Core-here covers the plugins, the CLI, the docs, and CI as much as the runtime under-`src/`. A private fork is created with a plain clone and never with-GitHub's fork feature, because a GitHub fork of a public repository cannot be made-private and its commits stay fetchable by SHA from the public side. The README section-"Customize your instance" gives the creation procedure.+Before acting, run `git remote -v` and inspect the checkout. `origin` pointing at+`yc-software/qm` identifies upstream. Another origin alone does not identify a source+fork: a package deployment has its own `qm.config.jsonc` and pinned `@yc-software/qm`+dependency, while a source fork carries the QM source tree and upstream ancestry.-Before you act, determine which repository this checkout is by running `git remote -v`.-If `origin` points at `yc-software/qm`, you are in upstream qm. If `origin`-points anywhere else, you are in a private fork, and five rules apply. Do not edit core;-a change to core belongs in upstream qm, and the `upstream-pr` skill sends it there-without leaking organization context. Keep every organization-specific file under-`deploy/layers/<org>/`. Sync from upstream with the `update-qm` skill, which merges and-never rebases. Pass `--repo` to every `gh` command, because `gh` may otherwise pick the-upstream repository through the `upstream` remote and read or edit the wrong-repository's pull requests. Never reference an upstream issue or pull request by number-(`yc-software/qm#123`) in a fork's PRs, issues, comments, or commit messages: GitHub-mirrors such mentions onto the referenced upstream item as a permanent timeline event,-so the fork's existence and the mentioning title become visible to whoever GitHub-decides may see them. Name upstream work in plain words instead.+Package deployments customize config, tools, skills, and services without copying core.+Source forks may modify core freely, including runtime, plugins, CLI, docs, and CI;+contributing those changes upstream is optional. Keep private deployment material under+`deploy/layers/<org>/` in private source forks or in a separate private deployment+repository for public source checkouts. Secrets never enter Git. The README section+"Customize your instance" documents both paths and explicit source builds.++Create private source forks as standalone repositories outside GitHub's fork network.+Seed only `main` and set the default branch explicitly; never use `git push --mirror`.+Use `update-qm` to merge source updates without rebasing published history or discarding+intentional local changes. Land source-sync PRs without squashing or rebasing away their+upstream ancestry. Package deployments update their dependency instead.++In downstream repositories, pass `--repo` to every `gh` command so the upstream remote+cannot redirect an operation. When contributing from private work, use `upstream-pr`+to prepare a clean branch and scrub outgoing content and history. Never reference an+upstream issue or PR by number in private repository PRs, issues, comments, or commit+messages: GitHub cross-references can disclose their existence and titles upstream.+Name upstream work in plain words instead.## Durable by defaultdiff --git a/README.md b/README.mdindex ff5daea7a..0a4d8c517 100644--- a/README.md+++ b/README.md@@ -161,52 +161,76 @@ not a public issue.## Customize your instance-The deployment repository above carries config and a sandbox layer, and never needs a-source checkout. Some organizations want the opposite trade: the whole codebase in one-place, so engineers and coding agents read core and customizations together, while the-customizations themselves stay private. For that, keep a **private fork**: a standalone-private repository whose history begins as a clone of qm and whose core stays identical-to upstream.+Choose how you want to customize QM:-Populate it once, then clone it to work in:+- **Config, tools, skills, and services:** use the deployment repository above. It+ pins `@yc-software/qm` and uses that release's runtime images; no source copy is needed.+- **Changes to QM itself:** keep your own source fork, public or private. You may+ modify any part of core, including the runtime, plugins, CLI, docs, and CI.+ Contributing those changes upstream is optional.++### Create a source fork++For a private source fork, create a standalone private repository, outside GitHub's+fork network. Seed only `main` and explicitly set it as the default branch:```bashgh repo create <org>/qm-private --private+git clone --single-branch --branch main --no-tags [email protected]:yc-software/qm qm-private+git -C qm-private remote rename origin upstream+git -C qm-private remote add origin [email protected]:<org>/qm-private+git -C qm-private push -u origin main+gh repo edit <org>/qm-private --default-branch main+```++Do not seed with `git push --mirror`: it copies unrelated upstream branches and tags,+leaves default-branch selection implicit, and can delete destination-only refs on later+pushes. The `upstream` remote supplies source updates without copying those refs to your+repository. For a public source fork, GitHub's Fork button is also an option. A GitHub+fork of a public repository cannot be private; keep private work outside that network.++Review inherited workflows before enabling Actions or adding credentials. Choose the CI+checks you want, and disable or adapt upstream release and publishing workflows for your+own package and image registries. Copying the source does not configure production+deployment CI.++### Customize and run your source-git clone --bare [email protected]:yc-software/qm qm-seed.git-git -C qm-seed.git push [email protected]:<org>/qm-private main-rm -rf qm-seed.git+Keep deployment configuration, tools, skills, plugin images, and infrastructure in+`deploy/layers/<org>/` in a private source fork, or in a separate private deployment+repository when your source is public. Never commit secrets. See+[`deploy/layers/README.md`](./deploy/layers/README.md) for initialization and layout.+Keep deployment data separate from core code, but change core wherever your desired+behavior requires it.-git clone [email protected]:<org>/qm-private-git -C qm-private remote add upstream [email protected]:yc-software/qm+From the source checkout, install dependencies with `npm ci` and use the in-tree CLI.+After completing the provider setup in [`deployment.md`](./deployment.md), build and+deploy your modified services explicitly:++```bash+node cli/bin/qm.ts check --config <deployment-dir>/qm.config.jsonc+node cli/bin/qm.ts plan --config <deployment-dir>/qm.config.jsonc --build-from .+node cli/bin/qm.ts up --config <deployment-dir>/qm.config.jsonc --build-from .+node cli/bin/qm.ts check --config <deployment-dir>/qm.config.jsonc --live```-Create the private fork with a plain clone, as shown above, and never with GitHub's fork-feature. The word "fork" here names the concept — a downstream copy that diverges-deliberately and merges from upstream — not GitHub's Fork button. A GitHub fork inherits-the visibility of the repository it came from, so a fork of a public repository cannot be-made private. A GitHub fork also shares one object network with the repository it came-from, so commits pushed to the fork stay fetchable by SHA from the public side. Many-organizations disallow forking private repositories as well. A plain clone has none of-these problems, and it costs one thing: the clone is an ordinary repository, so upstream's-CI workflows run live in your own account. Expect to supply the secrets those workflows-need, or disable the ones you do not want running.--Push `main` alone. A `--mirror` push copies every upstream branch and tag into the empty-repository, and GitHub then makes the alphabetically first branch the default, so pull-requests, clones, and tooling land on a stale feature branch instead of `main`. The-`update-qm` skill fetches everything else it needs from the `upstream` remote.--Everything specific to your organization goes in `deploy/layers/<org>/` — config, sandbox-tools and skills, plugin images, infrastructure — in the same shape `qm init` produces. See-[`deploy/layers/README.md`](./deploy/layers/README.md). Core stays byte-identical to-upstream, which is what keeps merges small.--Two skills maintain the boundary in both directions. `update-qm` merges upstream qm into-the private fork and opens the sync PR; `upstream-pr` sends an organization-agnostic fix back to-qm, cutting the branch from `upstream/main` and checking the outgoing diff, commit-messages, and screenshots for organization identifiers before it pushes. Nothing under-`deploy/layers/` ever travels upstream.+Use this checkout's CLI when changing the CLI itself. Without `--build-from`, the+normal deployment path selects published images, so editing source alone does not+change the deployed runtime. If you publish custom images instead, configure their+immutable references through `imageOverrides`. Follow the provider guide for sandbox+image builds; service builds do not replace that step.++### Keep it current++For a source fork, `update-qm` merges upstream changes while preserving intentional+local behavior. Land sync PRs with their merge ancestry intact, never squash or rebase+them. Conflicts are expected maintenance work, not a requirement to discard+customizations. Use `upstream-pr` only when you want to contribute a generic change;+it prepares a clean upstream branch without private deployment data or history.++For a package deployment, upgrade the exact `@yc-software/qm` dependency and lockfile,+review contract changes and generated assets, then validate and deploy. There is no+upstream source history to merge.## Going deeperdiff --git a/cli/src/commands/init.ts b/cli/src/commands/init.tsindex 4572fa8f4..b5d742973 100644--- a/cli/src/commands/init.ts+++ b/cli/src/commands/init.ts@@ -75,8 +75,8 @@ Run every command from this directory.3. After the target prerequisites are complete, \`npm exec qm -- up\` brings thedeployment up and prints the URLs. An AWS directory must first complete theedge and authenticated-portal steps in its AWS bootstrap section below.- \`--build-from <path to a QM checkout>\` is reserved for contributors- testing unreleased runtime code.+ \`--build-from <path to a QM checkout>\` builds modified runtime code+ from your source fork or a contributor checkout.4. \`npm exec qm -- status\`, \`npm exec qm -- logs [service]\`, and\`npm exec qm -- down\` showwhat is running, tail logs, and stop the deployment.diff --git a/deploy/layers/README.md b/deploy/layers/README.mdindex 785dda9f3..9dc794fe3 100644--- a/deploy/layers/README.md+++ b/deploy/layers/README.md@@ -1,13 +1,13 @@# Organization layers-This directory is where an organization's own deployment material lives when qm is-customized from a private fork: a standalone private repository whose history begins as-a clone of qm, in which core stays identical to upstream and everything-organization-specific is confined here, under `deploy/layers/<org>/`.+A private source fork can keep its deployment material under `deploy/layers/<org>/`.+Core code may change independently to implement the organization's desired behavior.+Public source checkouts keep private deployment material in a separate private+repository. Package deployments need only that deployment repository, with no source+fork. See [the README](../../README.md#customize-your-instance) for both paths.-In upstream qm this directory holds nothing but this file, and it stays that way. A layer-belongs to one organization's private fork and never travels upstream. The `upstream-pr` skill-enforces that boundary; the `update-qm` skill merges upstream changes in around it.+Upstream qm keeps only this shared README here. Organization layers never travel+upstream; `upstream-pr` checks that boundary when a contribution is requested.## Creating a layer@@ -41,6 +41,8 @@ Point the CLI at a layer with `--config`:node cli/bin/qm.ts check --config deploy/layers/<org>/qm.config.jsonc```+For a separate deployment directory, substitute its path in both commands.+Deploy modified services with the explicit `--build-from` workflow in the README.Run the CLI from the tree as shown. `npm exec qm` does not work in a source checkoutbecause the workspace symlink points at `cli/`, which is unbuilt.diff --git a/deployment.md b/deployment.mdindex d760de360..3cddaf75a 100644--- a/deployment.md+++ b/deployment.md@@ -5,5 +5,7 @@ The deployment workflow shipped by this repository isRead it completely and follow it as the authoritative workflow.The same file is materialized into every organization's deployment directory by-`qm init`, together with its agent skill and provider references. Customize and deploy-from a private fork of this repository; see [`deploy/layers/README.md`](deploy/layers/README.md).+`qm init`, together with its agent skill and provider references. Use a standalone deployment+repository for package deployments. To change QM source, follow the source-fork and+explicit build instructions in [the README](README.md#customize-your-instance); see+[`deploy/layers/README.md`](deploy/layers/README.md) for deployment layout.diff --git a/docs/deploy-directory.md b/docs/deploy-directory.mdindex 7bdc47a40..92ad5cdbb 100644--- a/docs/deploy-directory.md+++ b/docs/deploy-directory.md@@ -119,7 +119,7 @@ Postgres stores create their tables lazily with idempotent DDL through the share## Commands, conformance, and versioning-The normal gate order is `check`, `doctor`, `plan`, `up --yes`, then `check --live`. On AWS with MicroVM sandboxes, `infra build-image` precedes `plan`. First-party services come from the package's matching image manifest; `--build-from` is an explicit contributor escape hatch for unreleased source. `check` is static and has JSON output keyed to clause ids. `doctor` makes read-only external checks. `plan` renders without mutation. On AWS, rollback restores the prior recorded deployment manifest as one unit under the deployment lease; `--to` selects another complete manifest by manifest id or recorded release label. Because rollback restores code and configuration but never data, it prints the pre-deploy database point-in-time restore timestamp recorded on the deployment it rolls back (or the legacy snapshot for older manifests). Fly and Docker do not claim rollback.+The normal gate order is `check`, `doctor`, `plan`, `up --yes`, then `check --live`. On AWS with MicroVM sandboxes, `infra build-image` precedes `plan`. First-party services come from the package's matching image manifest; `--build-from` explicitly builds modified services from a source fork or contributor checkout; use the checkout's CLI when changing deployment logic too. `check` is static and has JSON output keyed to clause ids. `doctor` makes read-only external checks. `plan` renders without mutation. On AWS, rollback restores the prior recorded deployment manifest as one unit under the deployment lease; `--to` selects another complete manifest by manifest id or recorded release label. Because rollback restores code and configuration but never data, it prints the pre-deploy database point-in-time restore timestamp recorded on the deployment it rolls back (or the legacy snapshot for older manifests). Fly and Docker do not claim rollback.AWS `up` is mutually excluded by a DynamoDB lease, verifies RDS continuous backups and records the exact pre-mutation restore point, registers digest-pinned task definitions, enables the ECS circuit breaker, updates services, and waits stable. AWS `check --live` compares environment, secret routing, task definitions, and the configured release label in both directions. Fly `check --live` verifies every configured workload has a live image-bearing machine and the public health endpoint responds. `qm conformance` remains the later cross-check between the static contract and core's resolved deployment-layer descriptors.diff --git a/docs/getting-started.md b/docs/getting-started.mdindex 4d60c7971..01245b791 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -1,20 +1,23 @@# Deploy QM for an organizationDeploying QM does not require a copy of this repository: `qm init` materializes a-deployment directory from the published package, and the README section "Deploy it for-your org" gives that path. An organization that wants to customize its deployment keeps-a private fork of the QM repository and puts everything specific to itself in one-directory, `deploy/layers/<org>/`: its config, sandbox customizations, provider-coordinates, and generated Slack manifests. The rest of the tree stays identical to-upstream. See [`../deploy/layers/README.md`](../deploy/layers/README.md).--For a new layer, the agent first asks the operator for Fly.io or AWS (the slug-is a local name derived from the organization, not globally unique), then runs:+deployment directory from the published package. Start in an empty organization-owned+private repository:```bash-node cli/bin/qm.ts init deploy/layers/<org> --org <slug> --target <fly-or-aws>+npm exec --yes --package=@yc-software/qm@latest -- \+ qm init . --org <slug> --target <fly-or-aws>+npm install```+Choose Fly.io or AWS before initialization; the slug is a local name derived from the+organization, not globally unique. Customize config, tools, skills, and services in this+directory. To change QM itself, use a public or private source fork and explicitly+build its source, as described in [the README](../README.md#customize-your-instance).+A private source fork can keep its deployment at `deploy/layers/<org>/`; a public source+checkout uses a separate private deployment directory. See+[`../deploy/layers/README.md`](../deploy/layers/README.md).+Provider choice is part of initialization because it determines the config,secret rules, generated files, and teardown contract. Changing providers meansinitializing a new empty directory. `qm init` materializes `deployment.md` and