@oxy-hq/cli 0.1.0

package/template/.github/workflows/validate.yaml

@@ -0,0 +1,264 @@
+# Validate __NAME__'s semantic model on every pull request.
+#
+# `oxy compile` is the gate. It parses every workspace YAML file and writes the
+# result into a Postgres schema, so this job needs a throwaway database — and
+# it needs one more thing that is easy to miss: a row in `workspaces` for the
+# workspace id it compiles under. That row is created at `oxy serve --local`
+# boot, NOT by migrations, so a CI job that only migrates dies on a foreign-key
+# violation *before reading a single line of YAML*.
+#
+# Every step below was run against a real Postgres 16 container before it was
+# written here, on the pinned CLI version. If you change a step, run it — and
+# run it in BOTH layouts, since `OXY_WORKSPACE` below makes this file one that
+# has two correct answers rather than one.
+#
+# What this gate catches and what it does not: see "What CI checks" in README.md.
+
+name: validate
+
+on:
+  pull_request:
+  # Also on a push to the default branch, and the reason is not belt-and-braces.
+  # With `pull_request` alone this gate never ran at all on the workflow this
+  # template actually ships with: a scaffolded repo starts unprotected, work
+  # goes straight to main, and the compile check sat there being triggered by
+  # nothing. It stays useful once PRs are required too — a merge is a push, and
+  # a branch protected today can be unprotected tomorrow.
+  #
+  # Deliberately no `paths:` filter. `oxy compile` reads the whole workspace,
+  # and a filter that missed a path would skip validation silently, which is
+  # worse than compiling on a README change.
+  push:
+    branches: [main]
+
+# This gate reads the tree and compiles it into a throwaway database. It never
+# writes to the repository, so it does not need a token that can. Stated
+# explicitly because the DEFAULT is whatever the repo or org is set to, which
+# for many repos is read/write on every scope.
+permissions:
+  contents: read
+
+env:
+  # Pinned deliberately. `get.oxy.tech` honours OXY_VERSION, and this is the
+  # version the sequence below was proven against — bump it only after
+  # re-running the sequence, not on sight.
+  OXY_VERSION: "0.5.126"
+
+  # WHERE THE OXY WORKSPACE IS, relative to the repo root.
+  #
+  #   .     the repo IS the workspace — every repo `oxyc new` scaffolds
+  #   oxy   the repo CONTAINS one — the shape of every repo that was imported
+  #
+  # Substituted at render time from `__WORKSPACE__`, by the same machinery that
+  # writes __SLUG__ and __NAME__, so `oxyc update` re-renders it and there is no
+  # special case anywhere for a repo shaped the second way.
+  #
+  # It exists because this gate cannot be layout-agnostic and must not be
+  # layout-wrong: `oxy compile` at the repo root of a repo whose workspace is
+  # `oxy/` reads no config.yml, compiles nothing, and fails. A CI file that
+  # installs cleanly and then fails on every run is worse than one that was
+  # never installed.
+  #
+  # The TOOLING adapts to the repo, never the other way round. The platform
+  # registered this subdirectory when the workspace was onboarded and there is
+  # no UI or CLI to change it, so flattening a repo to match this template
+  # would silently break its registration with no repair short of re-onboarding.
+  OXY_WORKSPACE: "__WORKSPACE__"
+
+jobs:
+  compile:
+    name: oxy compile
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: ci
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      OXY_DATABASE_URL: postgres://postgres:ci@localhost:5432/postgres
+      # OXY_STATE_DIR is set per step, not here: the `runner` context is not
+      # available in a job-level `env:` block, and the expression would expand
+      # to the empty string — putting the CLI's state dir at "/oxy-state".
+      # actionlint catches this; a job that "just ran" would not.
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # This job runs a downloaded installer script. Without this, checkout
+          # leaves a GITHUB_TOKEN in .git/config for that script to find. The
+          # job-level `permissions: contents: read` already narrows what such a
+          # token could do; not persisting it at all is the cheaper half of the
+          # same argument, and it costs nothing here — nothing in this job
+          # pushes.
+          persist-credentials: false
+
+      - name: Install the pinned oxy CLI
+        run: |
+          set -euo pipefail
+          # NOT `bash <(curl ...)`, the form the docs use: process substitution
+          # hands bash an empty file when the download fails, and bash then
+          # exits 0 — a step that reports "installed" having installed nothing.
+          # Download to a file first so curl's own -f failure is the step's.
+          curl -sSfL https://get.oxy.tech -o "$RUNNER_TEMP/get-oxy.sh"
+          OXY_VERSION="$OXY_VERSION" bash "$RUNNER_TEMP/get-oxy.sh"
+
+          # And check the installer left something behind: it downloads the
+          # binary with `curl -L` (no -f) and exits 0 regardless.
+          if [ ! -x "$HOME/.local/bin/oxy" ]; then
+            echo "::error::the installer exited 0 but left no executable at $HOME/.local/bin/oxy." >&2
+            exit 1
+          fi
+
+          # The installer drops the binary in ~/.local/bin for a non-root user
+          # and edits shell rc files, which a GitHub step never reads. Put it
+          # on PATH explicitly instead of hoping.
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Verify the oxy CLI
+        run: |
+          set -euo pipefail
+          # Not ceremony. Two silent failures make this load-bearing:
+          #   1. the installer runs `curl -L` WITHOUT -f, so a tag that does
+          #      not exist writes GitHub's 404 HTML page to the binary path,
+          #      chmod +x's it, and still exits 0;
+          #   2. this CLI falls through to `--help` with exit 0 on a subcommand
+          #      it does not have, so an old binary "succeeds" at doing nothing.
+          if ! raw="$(oxy --version 2>&1)"; then
+            echo "::error::'oxy --version' failed — the installed binary is not runnable." >&2
+            printf '%s\n' "$raw" >&2
+            exit 1
+          fi
+
+          have="$(printf '%s\n' "$raw" | sed -n 's/^oxy-app version: \([0-9][0-9.]*\).*/\1/p' | head -1)"
+          if [ -z "$have" ]; then
+            echo "::error::could not read a version out of 'oxy --version' — the install probably wrote a 404 page." >&2
+            printf '%s\n' "$raw" >&2
+            exit 1
+          fi
+
+          oldest="$(printf '%s\n%s\n' "$OXY_VERSION" "$have" | sort -t. -k1,1n -k2,2n -k3,3n | head -1)"
+          if [ "$oldest" != "$OXY_VERSION" ]; then
+            echo "::error::oxy $have is older than the pinned $OXY_VERSION." >&2
+            exit 1
+          fi
+
+          echo "oxy $have (pin $OXY_VERSION)"
+
+      - name: Migrate the throwaway database
+        env:
+          OXY_STATE_DIR: ${{ runner.temp }}/oxy-state
+        run: oxy migrate
+
+      - name: Seed the workspace row oxy compile needs
+        run: |
+          set -euo pipefail
+          # `oxy compile --workspace-id` defaults to the nil UUID, and inserting
+          # a revision for it needs the matching `workspaces` row to exist.
+          # Migrations do not create it. Seeding it here is one INSERT against a
+          # database that is destroyed with the job; the alternative — booting
+          # `oxy serve --local` just to trigger its boot-time seed — costs ~25s,
+          # binds two ports, and has no "seed and exit" mode.
+          if ! command -v psql >/dev/null 2>&1; then
+            echo "::error::psql is not on this runner. GitHub's ubuntu-latest image ships it; a self-hosted runner may not. Install postgresql-client, or run this INSERT with: docker exec ${{ job.services.postgres.id }} psql -U postgres" >&2
+            exit 1
+          fi
+          psql "$OXY_DATABASE_URL" -v ON_ERROR_STOP=1 -q -c \
+            "INSERT INTO workspaces (id, name) VALUES ('00000000-0000-0000-0000-000000000000', 'ci-validate') ON CONFLICT (id) DO NOTHING;"
+
+      - name: Compile the workspace
+        env:
+          OXY_STATE_DIR: ${{ runner.temp }}/oxy-state
+        run: |
+          set -euo pipefail
+
+          # --workspace-path MUST be absolute. See the floor check below.
+          #
+          # $OXY_WORKSPACE is repo-RELATIVE, so it is joined to $GITHUB_WORKSPACE
+          # and then CANONICALISED rather than concatenated: `cd` + `pwd -P`
+          # collapses the trailing `/.` that a root workspace would otherwise
+          # leave in the path, and it fails HERE, naming the directory, instead
+          # of handing oxy a path that is not there. One expression, correct for
+          # a repo that is the workspace and for one that contains it.
+          ws=""
+          if ! ws="$(cd "$GITHUB_WORKSPACE/$OXY_WORKSPACE" 2>/dev/null && pwd -P)"; then
+            echo "::error::no directory at \$GITHUB_WORKSPACE/$OXY_WORKSPACE. OXY_WORKSPACE says where this repo's Oxy workspace is, relative to the repo root: '.' when the repo IS the workspace, a subdirectory name when it contains one." >&2
+            exit 1
+          fi
+          echo "workspace: $ws  (OXY_WORKSPACE=$OXY_WORKSPACE)"
+
+          status=0
+          oxy compile --workspace-path "$ws" --skip-migrations --json \
+            >"$RUNNER_TEMP/compile.stdout" 2>"$RUNNER_TEMP/compile.stderr" || status=$?
+
+          cat "$RUNNER_TEMP/compile.stderr" >&2
+
+          # `--json` does NOT put only JSON on stdout: a human-readable
+          # "Compiling workspace id=... path=..." line comes first, so piping
+          # stdout straight into jq fails ("Invalid numeric literal", exit 4).
+          # Extract from the line that opens the JSON object instead.
+          sed -n '/^{/,$p' "$RUNNER_TEMP/compile.stdout" > "$RUNNER_TEMP/compile.json"
+
+          if [ ! -s "$RUNNER_TEMP/compile.json" ]; then
+            echo "::error::oxy compile printed no JSON — it failed before compiling anything (database unreachable, or no workspaces row for --workspace-id)." >&2
+            exit 1
+          fi
+
+          # An empty .failures array is a legitimate result and jq exits 0 for
+          # it, so no `|| true` is needed — and `|| true` here would be wrong,
+          # since it would also swallow a real jq failure.
+          jq -r '.failures[] | "::error file=\(.path)::[\(.kind)] \(.message)"' "$RUNNER_TEMP/compile.json"
+          jq -r '"compile: status=\(.status) seen=\(.file_count_seen) compiled=\(.file_count_compiled) failed=\(.file_count_failed)"' "$RUNNER_TEMP/compile.json"
+
+          # Floor check, and it earns its place: `oxy compile --workspace-path .`
+          # finds config.yml and nothing else — every recursive kind is globbed
+          # as "<root>/**/*.view.yml", which matches nothing when <root> is "."
+          # — and it exits 0 while doing it. A green gate that validated no
+          # views is worse than no gate, so assert the walker saw at least the
+          # semantic files that are on disk.
+          seen="$(jq -r '.file_count_seen' "$RUNNER_TEMP/compile.json")"
+          floor=0
+          # Under $ws, not the checkout directory. In a repo whose workspace is
+          # `oxy/` the root has no config.yml, so a root-relative floor would
+          # sit one lower than the truth — quietly agreeing with a walk that saw
+          # nothing, which is the exact silence this check exists to break.
+          if [ -f "$ws/config.yml" ]; then
+            floor=$((floor + 1))
+          fi
+          # Count the WHOLE workspace tree, not just semantics/: the walker
+          # globs `**/*.view.yml` from the workspace root, so a view under
+          # models/ counts too, and a floor that only looked at semantics/ would
+          # sit at 1 and agree with a walk that saw nothing — the same silent
+          # agreement it exists to catch. Rooted at $ws for the same reason the
+          # config.yml check is: what the walker will descend into is the
+          # workspace, and a repo that contains one may hold .view.yml files
+          # outside it (a vendored fixture, an example) that the walker will
+          # never see and that would make this floor unreachably high.
+          # The prunes mirror the walker's own skip list; pruning a directory
+          # the walker would have descended can only UNDER-count, and a floor
+          # that is too low never fails a healthy repo.
+          # find prints nothing and exits 0 when there is no match, which is
+          # this repo's day-one state — a legitimate result, not an error to
+          # swallow. (On that empty tree floor=1=seen, so the check has nothing
+          # to detect and correctly says nothing.)
+          n="$(find "$ws" \( -name .git -o -name node_modules -o -name target \
+                  -o -name dist -o -name build -o -name .oxy_state \
+                  -o -name .semantics -o -name .preagg -o -name .worktrees \
+                  -o -name .cubestore -o -name .airlayer_cache \) -prune \
+                -o -type f \( -name '*.view.yml' -o -name '*.topic.yml' \) \
+                   ! -name '*.test.*' -print | wc -l | tr -d ' ')"
+          floor=$((floor + n))
+          if [ "$seen" -lt "$floor" ]; then
+            echo "::error::oxy compile saw $seen file(s) but at least $floor are on disk under $ws — the walker did not descend into the workspace. Check that --workspace-path is absolute, and that OXY_WORKSPACE ('$OXY_WORKSPACE') names the directory holding config.yml." >&2
+            exit 1
+          fi
+
+          exit "$status"

package/template/.nvmrc

@@ -0,0 +1 @@
+20

package/template/.oxyc-managed

@@ -0,0 +1,297 @@
+# Who owns each file in a repo scaffolded from this template, and which of a
+# repo's two trees each one describes.
+#
+# `oxyc update <customer>` brings an existing customer repo back in line with
+# `template/`, and the only question that matters when it does is which files it
+# may rewrite. The live customer repos are not scaffolds any more: one of them
+# carries 7 views, 4 topics, a pipeline, an app and five memory facts, and its
+# `package.json` differs from this template's because the customer added
+# dependencies for that app. A sync that overwrote what it did not own would
+# have eaten all of it.
+#
+# So the answer is written down HERE, next to the files, where whoever adds the
+# next template file has to walk past it. It was written a phase BEFORE the
+# command that reads it, on the same bet as `.oxyc-template.json`: the
+# classification is cheap to record now and impossible to recover later, once
+# repos exist that nobody can classify from memory.
+#
+# lib/sync.sh is the reader, and it decides nothing on its own — every role
+# below is taken from this file and `unmatched` is the default it falls back to.
+#
+# --- format -----------------------------------------------------------------
+#
+#   <directive> <glob>     one per line, whitespace-separated
+#   # ...                  comment, and blank lines are ignored
+#
+# The glob is matched against a path relative to the repo root, with a shell
+# `case`, so `*` spans `/` — `.github/workflows/*` covers any depth beneath it
+# and `*.gitkeep` covers every placeholder wherever it sits.
+#
+# There are TWO families of directive and they answer different questions:
+#
+#   managed / scaffold / mixed          who owns the bytes
+#   scope-repo / scope-workspace        which tree the file describes
+#
+# Each family has its own reader with its own allowlist, so a line from one is
+# invisible to the other and a typo in either (`manged`, `scope-wrokspace`) is
+# invisible to both — it falls to that family's default and fails the
+# completeness test in tests/template_ownership.bats rather than quietly
+# classifying a file under a word nothing recognises.
+#
+# --- the three roles, and what a wrong one costs ----------------------------
+#
+# managed   The TOOL owns the bytes. A sync may overwrite the file outright,
+#           and a customer edit to it is a mistake that a sync is entitled to
+#           undo. Classifying wrongly here is DATA LOSS.
+#
+# scaffold  Written once by `oxyc new` and never touched again. The customer
+#           owns it from the moment it lands. A sync may report that it has
+#           drifted; it may not rewrite it. Classifying wrongly here costs
+#           someone a manual copy — which is why anything genuinely uncertain
+#           belongs in this row rather than in `managed`.
+#
+# mixed     Both, in different PARTS of one file. A sync must merge, never
+#           replace, and until it can do that surgically it must report and
+#           leave the file alone.
+#
+#           That is the rule for a file that is THERE, and it is the only rule
+#           `oxyc update` has: a repo the tool scaffolded was given both halves
+#           on day one, so a mixed file missing from it was deleted on purpose
+#           and restoring it would undo somebody's decision. Update also runs
+#           over and over, and a command you run weekly must not quietly
+#           recreate what you removed.
+#
+#           `oxyc adopt` meets the other case, and answers it differently. An
+#           imported repo never had the file, so there is no customer half to
+#           protect — and withholding it strands the managed files it pairs
+#           with. The first real adopt did exactly that: pokehouse-oxy got
+#           `scripts/dev.sh` and no package.json, so the `"dev"` entry that
+#           runs the script was never created and `pnpm dev` could not work.
+#           It installed the tool and withheld the handle.
+#
+#           So adopt — a one-time act somebody types on purpose — installs a
+#           mixed file that is ABSENT and still never touches one that is
+#           PRESENT. Per FILE, not per role: pokehouse has a .gitignore, and
+#           that one is left exactly alone.
+#
+# --- and the role that is never written down: everything else ---------------
+#
+# unmatched  The CUSTOMER'S. A sync must not rewrite it, must not delete it,
+#            and must not ask — never touch it.
+#
+# That is a DEFAULT, not an omission, and it is the single most important rule
+# here. A scaffolded repo becomes mostly files this template never had: views,
+# topics, pipelines, an app bundle, pnpm-lock.yaml, memory facts. Every one of
+# them is unmatched BY CONSTRUCTION, and the file a sync does not recognise is
+# exactly the file it did not create.
+#
+# So the safe direction is built into the shape rather than remembered: a rule
+# has to be WRITTEN before anything may be rewritten, and forgetting to write
+# one can only ever make a sync do less.
+#
+# `mixed` exists because of one concrete case, and it is worth stating: the
+# root `package.json` holds a `"dev"` script entry that runs `scripts/dev.sh`.
+# That entry is tool-owned — it is the entry point to a tool-owned script, and
+# a customer deleting it has broken the local dev flow — while the
+# `dependencies` beside it are the customer's app's, and are exactly what a
+# blind overwrite would destroy. Two owners, one file. A two-way split would
+# have forced a choice between losing the entry and losing the dependencies.
+#
+# --- the second axis: which of a repo's TWO trees does a file describe? -----
+#
+# A role says who owns a file's bytes. It does not say what the file is ABOUT,
+# and in a repo `oxyc new` scaffolded there was never a difference to say: the
+# repo IS the workspace, so every path above is simply "at the root".
+#
+# An IMPORTED repo splits that in two, and the template's files land on both
+# sides of the split:
+#
+#   config.yml and README.md describe the OXY WORKSPACE. pokehouse-oxy keeps
+#   its workspace in `oxy/`, where a config.yml and a readme already sit,
+#   written by somebody before oxyc saw the repo. The template's copies
+#   describe nothing at that repo's root — and writing them there would build a
+#   second, half-populated workspace beside the real one.
+#
+#   package.json, pnpm-workspace.yaml and .gitignore describe the REPO ROOT,
+#   and are not Oxy workspace files at all. The first two are the PNPM
+#   workspace — a different workspace, which is where `scripts/dev.sh` is
+#   installed and where its `"dev"` entry has to live — and the third is the
+#   git working tree's ignore rules. All three belong at the root in both
+#   layouts, exactly as the managed machinery does.
+#
+# That distinction had nowhere to be written down, so lib/sync.sh inferred it
+# from the ROLE — `scaffold` and `mixed` were skipped together as "the
+# workspace's" — and the inference was wrong for all three of the second group.
+# pokehouse-oxy is what that cost. Adopted before the mixed-and-absent rule
+# landed, it has `scripts/dev.sh` and no package.json; adopt then refused it as
+# already-stamped, and update called package.json a workspace file and would
+# not so much as name the gap. The file could not arrive by any path.
+#
+# So it is written down, on its own lines, in its own vocabulary:
+#
+#   scope-repo       describes the REPO ROOT. Always in scope.
+#   scope-workspace  describes the OXY WORKSPACE. Out of scope in a repo that
+#                    keeps its workspace in a subdirectory; identical to
+#                    scope-repo in a repo that IS its workspace.
+#
+# A SECOND AXIS, and not a fourth role or a modifier on the three. The two
+# questions are independent — package.json is `mixed` AND repo-scoped,
+# config.yml is `scaffold` AND workspace-scoped — so a file that could answer
+# only one of them would lose the other. A fourth role would take config.yml's
+# `scaffold` away, which is the statement that a sync may report its drift and
+# never rewrite it, and buy nothing back. A modifier (`scaffold@workspace`)
+# keeps one line per file and breaks every reader instead: the
+# `case "$role" in managed)` arms in lib/sync.sh, lib/adopt.sh and lib/doctor.sh
+# stop matching a compound token, and in adopt_plan the fall-through is
+# `continue` — a file silently not installed, which is precisely the failure
+# this axis exists to end.
+#
+# THE DEFAULT IS `scope-repo`, and it deliberately points the OTHER WAY from
+# `unmatched` above. A wrong role costs DATA LOSS, so the role default has to
+# be the quiet one and forgetting a role can only make a sync do less. Scope
+# cannot cost data: it never widens what a role permits, and `scaffold` and
+# `mixed` are not written in any layout. What scope trades is NOISE against
+# SILENCE — and silence is the whole defect. Forget a `scope-workspace` line
+# and a file this repo will never have is reported on every run until somebody
+# writes it. Forget a `scope-repo` line under the opposite default and the file
+# can never arrive and nothing anywhere says so. The unwritten answer is
+# therefore the LOUD one.
+#
+# tests/template_ownership.bats requires both answers for every file the
+# template ships, so that default is unreachable from this manifest — it
+# governs only a manifest already failing its own test.
+
+# --- managed: the tool's own machinery --------------------------------------
+
+# CI. The workflows and the shell they call are versioned with the tooling,
+# pinned together (both files carry the same OXY_VERSION and a test enforces
+# it), and a customer editing them by hand is how a fleet of repos ends up on
+# eight different CI definitions.
+# The globs below match file EXTENSIONS rather than whole directories, and
+# that is deliberate. `scripts/*` would silently absorb a `scripts/NOTES.txt`
+# somebody adds next year into `managed` — a file nobody classified, in the
+# data-loss direction. Narrowed, that file is simply unmatched, which is both
+# the safe answer and a failing completeness test until a human decides.
+managed   .github/workflows/*.yaml
+managed   .github/workflows/*.yml
+managed   .github/scripts/*.sh
+
+# Local dev. Same argument: `scripts/dev.sh` is the tooling's answer to "run an
+# app locally", and it is meant to improve for everyone at once.
+managed   scripts/*.sh
+
+# The merge rule for the generated memory index. It is a statement about how
+# oxyc's own generated file behaves, so oxyc owns it.
+managed   .gitattributes
+
+# This file.
+managed   .oxyc-managed
+
+# Not a template file at all — `oxyc new` writes it at render time, and
+# `oxyc update --apply` re-points it at the commit it synced from. Listed here
+# so that the sync's right to rewrite it is recorded in the same place as
+# everything else's, rather than being a special case buried in code.
+managed   .oxyc-template.json
+
+# DELIBERATELY ABSENT: `.oxyc.json`, the repo's own statement about where its
+# Oxy workspace is (see lib/workspace.sh). No rule is written for it, which
+# means it falls to `unmatched` — the customer's, never touch — and that is
+# exactly right twice over. It is hand-written, so a sync rewriting it would
+# undo a decision somebody made; and it is the file that tells the sync what
+# shape the repo is, so a sync that overwrote it would be sawing off the branch
+# it stands on. Named here only so that the absence reads as a decision.
+#
+# This template does not ship one, either: a scaffolded repo is a workspace at
+# its root, detection settles that unaided, and shipping an override would make
+# the exception look like the norm.
+
+# --- scaffold: the customer's from the moment it lands ----------------------
+
+# Both are edited immediately and permanently: config.yml gains the models and
+# databases of a real workspace, README.md gains whatever the team needs to say
+# about this customer.
+scaffold  config.yml
+scaffold  README.md
+
+# Node version. A single line, and the customer may legitimately move it — an
+# app that needs a newer runtime is their call, not the tooling's. There is no
+# tool-owned structure inside it to merge, so `mixed` would mean nothing here;
+# a sync that forced it back would be an unrequested downgrade, so `managed` is
+# wrong too. Report the drift and let a human decide.
+scaffold  .nvmrc
+
+# Placeholders that exist only so git carries an empty directory. Once a real
+# view or pipeline lands beside one, the customer usually deletes it — and a
+# sync that recreated it would be resurrecting a file somebody removed on
+# purpose. Written once, then never ours again.
+scaffold  *.gitkeep
+
+# --- mixed: two owners, one file --------------------------------------------
+
+# The case the third role exists for; see the note at the top.
+mixed     package.json
+
+# The `.gitignore` rules this template ships are load-bearing — dropping
+# `node_modules/` or `out/` commits a build tree on the customer's next
+# `git add -A`, and a test in customer-tooling pins the exact rule lines — so
+# those lines are the tool's. Anything the customer adds below them is theirs
+# and is expected: a scratch directory, an app-specific artifact. Both at once,
+# which is `mixed`, not a judgement call between the two.
+mixed     .gitignore
+
+# Same shape, and the file says so itself: the `onlyBuiltDependencies` block
+# carries the three entries the shipped app bundles need, with an instruction
+# to ADD to the list rather than replace it. The `packages:` globs are the
+# tool's; a fourth dependency that needs its install script run is the
+# customer's.
+mixed     pnpm-workspace.yaml
+
+# --- scope: which tree each file describes ----------------------------------
+#
+# Grouped by answer rather than written beside the role above, so that the two
+# axes are never read as one column of five roles. Every file the template
+# ships appears here exactly once, the same rule the roles are held to.
+
+# THE REPO ROOT. All of the managed machinery first: CI runs from the repo root
+# in both layouts, `.github/scripts/` is what it calls, and the stamp and this
+# manifest describe the repo oxyc adopted rather than the workspace inside it.
+scope-repo       .github/workflows/*.yaml
+scope-repo       .github/workflows/*.yml
+scope-repo       .github/scripts/*.sh
+scope-repo       scripts/*.sh
+scope-repo       .gitattributes
+scope-repo       .oxyc-managed
+scope-repo       .oxyc-template.json
+
+# The PNPM workspace and the git working tree, which are root things in a repo
+# whose Oxy workspace is somewhere else. `pnpm dev` is run from the repo root;
+# `packages: apps/*` names directories at the repo root, which is also where
+# `.github/scripts/discover-apps.sh` globs for bundles; `.gitignore` governs
+# what `git add -A` stages across the whole repo, `node_modules/` and `out/`
+# included. `.nvmrc` is the node version all of that builds under.
+scope-repo       package.json
+scope-repo       pnpm-workspace.yaml
+scope-repo       .gitignore
+scope-repo       .nvmrc
+
+# Two placeholders whose directories are also the repo's, not the workspace's.
+# `memory/` is about the CUSTOMER and sits at the repo root in both shapes —
+# lib/workspace.sh says so beside memory_dir, and it is the one directory oxyc
+# creates in a repo it did not scaffold. `apps/` is where publish.yaml looks
+# for bundles, from the repo root, and it is what pnpm-workspace.yaml declares.
+scope-repo       memory/.gitkeep
+scope-repo       apps/.gitkeep
+
+# THE OXY WORKSPACE. config.yml IS the workspace — it is the file
+# workspace_resolve looks for, and finding it one level down is what makes a
+# repo a subdirectory repo in the first place — and README.md is that
+# workspace's own readme, describing the layout below it. An imported repo has
+# both already, inside `oxy/`, and its root README is the project's.
+scope-workspace  config.yml
+scope-workspace  README.md
+
+# The placeholders holding open the workspace's own directories. They live
+# beside config.yml in a scaffolded repo and inside `oxy/` in an imported one.
+scope-workspace  pipelines/.gitkeep
+scope-workspace  workflows/.gitkeep
+scope-workspace  semantics/*/.gitkeep