Skip to content

armgit / qm

Public Imported from GitHub
0

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.md
index 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 main
git pull --ff-only origin main
git fetch upstream
-git switch -c sync-upstream-<yyyy-mm-dd>
+git switch -c codex/sync-upstream-<yyyy-mm-dd>
git log --oneline main..upstream/main
git 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 ci
npm run typecheck
npm 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 unbu
node 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 checks
above.
+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 that
adds or changes CI changes what runs on the next PR, and workflows that need secrets the
fork 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.yaml
index 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.md
index 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 is
permanent: 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 push
target 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 fork
feature and living inside qm's fork network: push to `origin` and open a normal
cross-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 upstream
Ask what the change would mean to an organization that is not yours. It belongs upstream
when it is a fix or capability in core qm that any deployment would want. It does not
belong 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 its
fixtures 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 and
change, which is why the pattern matches only paths inside an organization's
subdirectory.
-**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 cloud
account 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, the
prior 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 leaked
diff --git a/AGENTS.md b/AGENTS.md
index 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 default
diff --git a/README.md b/README.md
index 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:
```bash
gh 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 deeper
diff --git a/cli/src/commands/init.ts b/cli/src/commands/init.ts
index 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 the
deployment up and prints the URLs. An AWS directory must first complete the
edge 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\` show
what is running, tail logs, and stop the deployment.
diff --git a/deploy/layers/README.md b/deploy/layers/README.md
index 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 checkout
because the workspace symlink points at `cli/`, which is unbuilt.
diff --git a/deployment.md b/deployment.md
index d760de360..3cddaf75a 100644
--- a/deployment.md
+++ b/deployment.md
@@ -5,5 +5,7 @@ The deployment workflow shipped by this repository is
Read 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.md
index 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.md
index 4d60c7971..01245b791 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -1,20 +1,23 @@
# Deploy QM for an organization
Deploying 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 means
initializing a new empty directory. `qm init` materializes `deployment.md` and