Merge pull request #1058 from fullsend-ai/fix-adr-35

docs(adr-35): cover per-repo install mode in layered content resolution

Author: waynesun09

docs/ADRs/0035-layered-content-resolution.md

@@ -39,29 +39,49 @@ at runtime, enabling a workspace merge that implements the layering model.
 
 ## Decision
 
-Three coordinated changes:
+Three coordinated changes, applied uniformly to both installation modes
+(per-org and per-repo):
 
-**A. Org customizations live in `customized/`.** The scaffold installs a
+**A. Customizations live in `customized/`.** The scaffold installs a
 `customized/` directory with empty subdirs (`agents/`, `skills/`, `schemas/`,
-`harness/`, `policies/`, `scripts/`, `env/`) containing `.gitkeep` files. Orgs add
-overrides here. The main dirs are not in the `.fullsend` repo — they are
-populated at runtime from upstream.
+`harness/`, `policies/`, `scripts/`, `env/`) containing `.gitkeep` files. The
+location differs by install mode:
+
+- **Per-org** (`fullsend admin install <org>`): `customized/` in the org-level
+  `<org>/.fullsend` repo. Orgs add overrides here that apply to all enrolled
+  repos.
+- **Per-repo** (`fullsend admin install <owner/repo>`): `.fullsend/customized/`
+  in the target repo itself. The repo adds overrides that apply only to that
+  repo.
+
+In both cases the main dirs (`agents/`, `skills/`, etc.) are not committed —
+they are populated at runtime from upstream.
 
 **B. Runtime layering via reusable workflows.** Each reusable workflow adds a
 "Prepare workspace" step that sparse-checkouts upstream defaults from
 `fullsend-ai/fullsend@v0`, copies them into the main dirs (`agents/`, `skills/`,
-etc.), then copies `customized/*` on top so org files overwrite upstream
-defaults. The harness sees a single flat workspace — no changes to
+etc.), then copies customizations on top so override files replace upstream
+defaults. The workflow inspects `install_mode` to resolve the correct
+customization base:
+
+- `per-org`: reads from `customized/`
+- `per-repo`: reads from `.fullsend/customized/`
+
+The harness sees a single flat workspace in both modes — no changes to
 `ResolveRelativeTo()` or `--fullsend-dir`.
 
 **C. Scaffold stops writing upstream defaults.** `WalkFullsendRepo` skips files
 in layered directories (`agents/`, `skills/`, `schemas/`, `harness/`,
 `policies/`, `scripts/`, `env/`) and upstream-only directories (`.github/actions/`,
-`.github/scripts/`). The installer writes only org-specific files and
-`customized/` gitkeeps.
+`.github/scripts/`). The installer writes only mode-specific files and
+`customized/` gitkeeps. `CustomizedDirs()` returns paths for per-org installs;
+`PerRepoCustomizedDirs()` returns `.fullsend/customized/` paths for per-repo
+installs.
 
 File categories after this change:
 
+**Per-org install** (`<org>/.fullsend` repo):
+
 - **Org-only** (~11 files): `dispatch.yml`, thin callers, shim template,
   `AGENTS.md` — always installed, never overwritten by upstream.
 - **Org overrides** (7 `.gitkeep` files):
@@ -73,14 +93,26 @@ File categories after this change:
 - **Upstream infrastructure** (~5 files): composite actions,
   `setup-agent-env.sh` — referenced directly from upstream, never in `.fullsend`.
 
+**Per-repo install** (target repo):
+
+- **Repo scaffolding** (~2 files): `.github/workflows/fullsend.yaml` (shim
+  workflow), `.fullsend/config.yaml` (per-repo config).
+- **Repo overrides** (7 `.gitkeep` files):
+  `.fullsend/customized/{agents,skills,schemas,harness,policies,scripts,env}/` —
+  scaffold creates the structure, repo owners add real files.
+- **Upstream defaults** and **Upstream infrastructure**: same as per-org — provided
+  at runtime, never committed to the repo.
+
 ## Consequences
 
-- Fresh install produces a slim `.fullsend` repo (~24 files instead of ~82).
-- Upgrades never overwrite org content — the installer does not touch
-  customizable content.
+- Fresh per-org install produces a slim `.fullsend` repo (~24 files instead of
+  ~82). Per-repo install adds only ~16 files to the target repo.
+- Upgrades never overwrite customized content — the installer does not touch
+  files in `customized/` (per-org) or `.fullsend/customized/` (per-repo).
 - Upstream improvements to agents, skills, and schemas appear automatically at
-  runtime without re-install.
-- Org overrides are explicit and auditable in `customized/`.
+  runtime without re-install, regardless of install mode.
+- Overrides are explicit and auditable: in `customized/` for per-org, in
+  `.fullsend/customized/` for per-repo.
 - Requires a public upstream repo (`fullsend-ai/fullsend` is already public).
 - Runtime availability: sparse checkout of upstream defaults requires
   github.com to be reachable at workflow execution time. GitHub Actions already