context-packs 0.2.0 → 0.3.0

package/README.md

@@ -27,26 +27,47 @@ Run it with `npx context-packs`, or [let your agent run it](#let-your-agent-run-
 
 ## Write a pack
 
-A pack is a folder in any git repo. `pack.md` holds the rules every session sees, and each doc set, one `.md` file or a folder with an `index.md`, covers a topic agents read about only when it's relevant:
+A pack is a folder in any git repo. `pack.md` holds the rules every session sees, and every other `.md` file is a doc agents read only when it's relevant. A folder holding a `pack.md` of its own is a nested pack, and a folder without one just groups files:
 
 ```text
 context/
 ├── pack.md          # rules pasted into every repo's AGENTS.md
-├── testing.md       # a doc set in one file
-└── typescript/
-    ├── index.md     # a doc set's entry point
-    └── react.md     # linked from index.md
+├── testing.md       # a doc
+├── git/
+│   └── prs.md       # a doc, grouped in a folder
+└── typescript/      # a nested pack
+    ├── pack.md
+    ├── types.md
+    └── react/       # a nested pack inside it
+        └── pack.md
 ```
 
-Each doc set starts with front matter. `when` becomes its row in the table, and `tier: required` installs it in every repo; without it, the set is optional and each repo chooses it with `--docs`.
+Each doc starts with front matter whose `when` becomes its row in the table:
 
 ```markdown
 ---
 when: Writing or changing tests
-tier: required
 ---
 ```
 
+A nested pack gets a row too, from the `when` in its `pack.md`, pointing at a generated index that holds its rules and a table of its own docs and nested packs. Each nested pack is a read an agent makes before reaching the docs inside it, so nest only where a subtree is big and its `when` is sharp, and use plain folders to group the rest. Files other than `.md` files, such as code examples, are copied along with the docs beside them.
+
+A nested pack's `pack.md` takes two more fields:
+
+- `optional: true` leaves it out unless a repo picks it with `--docs`. Without it, the nested pack is installed whenever its parent is.
+- `inline: true` pastes its rules and table after its parent's instead of giving it a row, for rules that apply whenever a repo has the nested pack, like a language's. An inline pack that isn't optional needs no `when`.
+
+```markdown
+---
+when: Working in a TypeScript repo
+optional: true
+inline: true
+---
+Prefer unions to enums.
+```
+
+Any folder with a `pack.md` can also be installed on its own, as its own pack, and it renders the way it would inside its parent. If its `pack.md` has a `when` and isn't inline, its block in `AGENTS.md` is a one-row table pointing at a generated index of its rules, so installing just `typescript` still loads its rules only when a row matches. Without a `when`, or with `inline: true`, its rules are pasted into the block. `optional` doesn't apply, since installing it is the pick.
+
 Keep `pack.md` short, since every session loads it.
 
 Tags are optional. A repo pins to a commit by default, and `update` moves it to the tip of your default branch. Tag releases like `v1.2.0` once you want repos to pin to versions and `update` from one release to the next.
@@ -61,13 +82,13 @@ npx context-packs add <name> <git-url> --path <folder>
 - `<git-url>` is the repo holding the pack, as you'd pass it to `git clone`.
 - `<folder>` is the pack's folder in that repo, such as `context`. Leave out `--path` if the pack is the whole repo.
 
-That adds the pack's block to `AGENTS.md`, creating it if needed, and copies the doc sets into `docs/agents/packs/<name>/`, pinned to the origin's latest commit or to `--ref <tag or commit>`. Commit the result. If `AGENTS.md` already exists, the first run prints two marker lines to paste where the shared rules should go; then run it again.
+That adds the pack's block to `AGENTS.md`, creating it if needed, and copies the docs into `docs/agents/packs/<name>/`, pinned to the origin's latest commit or to `--ref <tag or commit>`. Commit the result. If `AGENTS.md` already exists, the first run prints two marker lines to paste where the shared rules should go; then run it again.
 
 Later, `npx context-packs update` moves packs to their latest version, and `npx context-packs` resyncs at the pinned ones. Private repos work, since origins are fetched with your own git credentials.
 
 ## Sync your project's own docs
 
-The same table works for a repo's own docs. Put each in a folder with a `when:` line, and install the folder as a pack read from the working tree:
+The same table works for a repo's own docs. Put them in a folder, each with a `when:` line, and install the folder as a pack read from the working tree:
 
 ```bash
 npx context-packs add <name> . --path <folder>
@@ -83,7 +104,7 @@ Any name and folder work. We suggest `project` and `docs/agents/project`:
 npx context-packs add project . --path docs/agents/project
 ```
 
-Its table points at the docs where they are. Resync after adding a doc or changing a `when:` line.
+Its table points at the docs where they are, and only its nested packs' indexes are generated, into `docs/agents/packs/<name>/`. Resync after adding a doc or changing a `when:` line or a nested pack's rules.
 
 ## Let your agent run it
 
@@ -99,7 +120,7 @@ Then ask things like:
 
 - "Add the context pack in the `context` folder of github.com/acme/agent-rules"
 - "Update our context packs"
-- "Install the typescript docs from team-rules"
+- "Install the typescript pack from team-rules"
 - "Sync our project docs"
 
 In Claude Code, `/context-packs` invokes it directly.
@@ -111,15 +132,15 @@ Each command syncs the current folder, or `--dir <folder>`, and prints what chan
 | Command | Does |
 |---|---|
 | *(none)* | Resyncs every pack at its pinned ref |
-| `add <name> <origin> [--path P] [--ref R] [--docs a,b]` | Installs a pack, pinned to the origin's latest commit or to `--ref` |
+| `add <name> <origin> [--path P] [--ref R] [--docs a,b]` | Installs a pack, pinned to the origin's latest commit or to `--ref`, with the optional nested packs in `--docs` |
 | `remove <name>` | Uninstalls a pack |
 | `update [name…]` | Moves packs to their latest version |
 | `update <name> --ref R` | Pins one pack to a tag or commit |
-| `docs <name> a,b` | Replaces a pack's optional doc sets (`''` for none) |
-| `list` | Lists each pack and its doc sets, marking the installed ones |
+| `docs <name> a,b` | Replaces the optional nested packs a pack installs, each named by its path such as `typescript/react` (`''` for none). Picking one installs the packs above it |
+| `list` | Lists each pack and its nested packs as a tree, marking the installed ones |
 
 **Pinning.** `--ref` takes a tag or a commit, never a branch, since a branch moves. `update` moves a pack pinned to a commit to the tip of the default branch, and one pinned to a release tag (a prefix and dot-separated numbers, such as `v1.2.0` or `acme-v3`) to the newest release with the same prefix, skipping pre-releases. Other tags stay put.
 
-**Edits stay upstream.** Each block ends with a hash of its text and synced docs. If either was edited in the repo, the sync stops and says what to fix: change the pack in its origin, then `update`.
+**Edits stay upstream.** Each block ends with a hash of its text and the files under its `docs/agents/packs/<name>/`. If either was edited in the repo, the sync stops and says what to fix: change the pack in its origin, then `update`.
 
 **Contributing.** [design.md](docs/agents/project/design.md) explains the choices behind the format. Run the tests with `python3 -m unittest discover tests`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-packs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Sync shared agent rules and docs into each repo's AGENTS.md",
   "license": "MIT",
   "bin": {

package/src/blocks.py

@@ -1,4 +1,4 @@
-"""The context-packs blocks in AGENTS.md, and the doc sets each pack installed beside them."""
+"""The context-packs blocks in AGENTS.md, and the files each pack wrote beside them."""
 import hashlib
 import re
 import sys
@@ -11,22 +11,20 @@ HEADER_START = '<!-- context-packs:start header -->\n'
 HEADER_RULES = (
     '## Context Packs\n\n'
     'Context packs bring shared rules and docs in from elsewhere. Each pack has a block in this file holding its rules '
-    "and a table of its context docs. Before starting work that a row in a pack's table matches, read its doc. "
-    f"A pack's block, and any of its docs under `{PACKS.as_posix()}/`, are copied from the `from` and `path` in the "
-    "block's start marker: change them there, never here.\n")
+    'and a table of its context docs, and a doc may hold a table of its own. Before starting work that a row in any '
+    f"of these tables matches, read its doc. A pack's block, and everything under `{PACKS.as_posix()}/`, are "
+    "generated from the `from` and `path` in the block's start marker: change them there, never here.\n")
 BLOCK = re.compile(r'^<!-- context-packs:start (\S+)((?: \S+)*) -->\n(.*?)'
                    r'^<!-- context-packs:end sha256:([0-9a-f]{12}) -->\n?', re.MULTILINE | re.DOTALL)
 
 
 class Region(NamedTuple):
-    """Where AGENTS.md's context-packs blocks sit, each block's text by name, the packs they hold, and the doc sets
-    each installed."""
+    """Where AGENTS.md's context-packs blocks sit, each block's text by name, and the packs they hold."""
     text: str
     start: int
     end: int
     blocks: Dict[str, str]
     packs: List[Pack]
-    installed: Dict[str, List[str]]
 
 
 def digest(body, docs=b''):
@@ -45,33 +43,18 @@ def snapshot(folder):
                     for p in sorted(folder.rglob('*')) if p.is_file())
 
 
-def installed(repo, folder):
-    """The doc sets copied into folder: each a folder holding an index.md, or a single .md file."""
-    if not (repo / folder).is_dir():
-        return []
-    names = []
-    for entry in (repo / folder).iterdir():
-        if (entry / 'index.md').is_file():
-            names.append(entry.name)
-        elif entry.is_file() and entry.suffix == '.md':
-            names.append(entry.stem)
-        else:
-            sys.exit(f'context-packs: {(folder / entry.name).as_posix()} is not a doc set, since it\'s neither a '
-                     '.md file nor a folder with an index.md. Remove it, then sync again.')
-    return sorted(names)
-
-
 def marked_pack(agents_md, name, marker):
     pairs = [field.split('=', 1) for field in marker.split()]
     fields = dict(p for p in pairs if len(p) == 2)
     origin = fields.get('from')
-    if (len(fields) != len(pairs) or set(fields) - {'from', 'path', 'ref'} or not origin
+    if (len(fields) != len(pairs) or set(fields) - {'from', 'path', 'ref', 'docs'} or not origin
             or (origin == LOCAL) == ('ref' in fields)):
         sys.exit(f'context-packs: {agents_md}: the {name} block\'s start marker needs from=<git URL> and '
                  'ref=<tag or commit>, or from=. for a pack in this repo, plus path=<folder> unless the pack is the '
-                 'whole repo. '
+                 'whole repo, and docs=<nested packs> for the optional ones picked. '
                  'Fix the marker, then sync again.')
-    return Pack(name, origin, fields.get('path', ''), fields.get('ref'))
+    docs = tuple(fields['docs'].split(',')) if 'docs' in fields else ()
+    return Pack(name, origin, fields.get('path', ''), fields.get('ref'), docs)
 
 
 def region(repo):
@@ -99,18 +82,15 @@ def region(repo):
             sys.exit(f'context-packs: {agents_md} has text between the context-packs blocks, which must sit together '
                      'separated by blank lines. Move it outside them, then sync again.')
     packs = [marked_pack(agents_md, m.group(1), m.group(2)) for m in blocks[1:]]
-    copied = {p.name for p in packs if not p.local}
     if (repo / PACKS).is_dir():
         for entry in sorted((repo / PACKS).iterdir()):
-            if entry.name not in copied:
-                sys.exit(f'context-packs: {(PACKS / entry.name).as_posix()} has no block in {agents_md} for a pack '
-                         'copied from another repo. Remove it, then sync again.')
-    current = {p.name: installed(repo, p.synced) for p in packs if not p.local}
+            if entry.name not in names[1:]:
+                sys.exit(f'context-packs: {(PACKS / entry.name).as_posix()} has no block in {agents_md}. '
+                         'Remove it, then sync again.')
     for match in blocks:
         name, _, synced, sha = match.groups()
-        if digest(synced, snapshot(repo / PACKS / name) if name in copied else b'') != sha:
+        if digest(synced, snapshot(repo / PACKS / name)) != sha:
             sys.exit(f'context-packs: {agents_md}: the {name} block or a doc in {PACKS / name} was edited since '
                      'the last sync. Move the change into its context pack or outside them, revert it, '
                      'then sync again.')
-    return Region(text, blocks[0].start(), blocks[-1].end(), {m.group(1): m.group(0) for m in blocks}, packs,
-                  current)
+    return Region(text, blocks[0].start(), blocks[-1].end(), {m.group(1): m.group(0) for m in blocks}, packs)

package/src/cli.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 """Sync context packs into a repository, or any folder such as the one above the repositories: each pack's rules as a
-block in AGENTS.md, after a header block explaining context packs, and each pack's required doc sets and the ones the
-repository chose in docs/agents/packs/<pack>/."""
+block in AGENTS.md, after a header block explaining context packs, and each pack's docs and the nested packs it
+installs in docs/agents/packs/<pack>/."""
 import argparse
 import contextlib
+import itertools
 import os
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 import re
 import shutil
 import sys
@@ -13,18 +14,18 @@ import sys
 import origins
 import report
 from blocks import HEADER, HEADER_RULES, HEADER_START, block, region, snapshot
-from packs import LOCAL, PACKS, Pack, Source, fetch
+from packs import LOCAL, PACKS, Pack, fetch
+import tree
 
 
 def sets(text):
-    return {n for n in text.split(',') if n}
+    return tuple(sorted({n for n in text.split(',') if n}))
 
 
 def apply(args, found):
-    """The packs, and the optional doc sets each should have, once the command has run."""
+    """The packs, each with the optional nested packs it should have, once the command has run."""
     packs = list(found.packs)
     names = [p.name for p in packs]
-    picked = {p.name: set(found.installed.get(p.name, [])) for p in packs}
     if args.command == 'add':
         if not re.fullmatch(r'[A-Za-z0-9._-]+', args.name) or args.name == HEADER:
             sys.exit(f'context-packs: {args.name} can\'t name a pack. '
@@ -34,13 +35,10 @@ def apply(args, found):
         if args.origin == LOCAL:
             if args.ref:
                 sys.exit('context-packs: a pack in this repo syncs from its working tree, so it takes no --ref.')
-            if args.docs:
-                sys.exit('context-packs: a pack in this repo installs every doc set it has, so it takes no --docs.')
             ref = None
         else:
             ref = origins.pin(args.origin, args.ref) if args.ref else origins.tip(args.origin)
-        packs.append(Pack(args.name, args.origin, args.path, ref))
-        picked[args.name] = sets(args.docs)
+        packs.append(Pack(args.name, args.origin, args.path, ref, sets(args.docs)))
     named = [args.name] if args.command in ('remove', 'docs') else getattr(args, 'names', [])
     unknown = [n for n in named if n not in names]
     if unknown:
@@ -49,10 +47,8 @@ def apply(args, found):
     if args.command == 'remove':
         packs = [p for p in packs if p.name != args.name]
     if args.command == 'docs':
-        if next(p for p in packs if p.name == args.name).local:
-            sys.exit(f'context-packs: the {args.name} pack is in this repo, so it installs every doc set it has. '
-                     'Delete a doc to drop it.')
-        picked[args.name] = sets(args.sets)
+        i = names.index(args.name)
+        packs[i] = packs[i]._replace(docs=sets(args.sets))
     if args.command == 'update':
         if args.ref and len(named) != 1:
             sys.exit('context-packs: --ref pins one pack, so name exactly one.')
@@ -66,21 +62,32 @@ def apply(args, found):
                 continue
             packs[i] = pack._replace(ref=origins.pin(pack.origin, args.ref) if args.ref
                                      else origins.latest(pack.origin, pack.ref))
-    return packs, picked
-
-
-def show(sources, picked):
-    for source in sources:
-        pack = source.pack
+    # The folder inside would sync twice, maybe at another ref. Origins compare as written, so the same repo spelled
+    # two ways gets past this.
+    for a, b in itertools.combinations(packs, 2):
+        outer, inner = sorted((PurePosixPath(a.path).parts, PurePosixPath(b.path).parts), key=len)
+        if a.origin == b.origin and inner[:len(outer)] == outer:
+            sys.exit(f'context-packs: the {a.name} and {b.name} packs overlap: one\'s folder in {a.origin} holds the '
+                     'other\'s, so its rules would sync twice. Keep only one of them.')
+    return packs
+
+
+def show(packs, roots):
+    """Each pack, then its nested packs as a tree, marking the installed ones and why each was installed if it
+    wasn't picked."""
+    for pack in packs:
         print(f'{pack.name}  {pack.origin}' + f'  {pack.path}' * bool(pack.path) + f' @ {pack.ref}' * bool(pack.ref))
-        for name in source.available():
-            fields = source.front(name)
-            if pack.local:
-                print(f'  [x] {name}: {fields["when"]}')
-            elif fields.get('tier') == 'required':
-                print(f'  [x] {name} (required): {fields["when"]}')
-            else:
-                print(f'  [{"x" if name in picked[pack.name] else " "}] {name}: {fields["when"]}')
+        installed = tree.installs(roots[pack.name], pack)
+
+        def lines(node, depth):
+            for child in node.children:
+                below = [p for p in pack.docs if p.startswith(f'{child.id}/')]
+                why = (f' (needed by {", ".join(below)})' if child.optional and child.id in installed
+                       and child.id not in pack.docs else '')
+                when = f': {child.fields["when"]}' if 'when' in child.fields else ''
+                print(f'{"  " * depth}[{"x" if child.id in installed else " "}] {child.id}{why}{when}')
+                lines(child, depth + 1)
+        lines(roots[pack.name], 1)
 
 
 def main():
@@ -94,7 +101,7 @@ def main():
     add.add_argument('origin', help='a git URL, or . for a folder in the synced repo itself')
     add.add_argument('--path', default='', help='the folder in the origin holding the pack, if not its root')
     add.add_argument('--ref', help='a tag or commit to pin the pack to')
-    add.add_argument('--docs', default='', help='comma-separated optional doc sets to install')
+    add.add_argument('--docs', default='', help='comma-separated optional nested packs to install')
     remove = commands.add_parser('remove', help='uninstall a pack')
     remove.add_argument('name')
     update = commands.add_parser('update', help='move pinned packs on: one pinned to a commit to the tip of its '
@@ -102,22 +109,23 @@ def main():
                                                 'release in its series')
     update.add_argument('names', nargs='*', help='the packs to update; all of them if left out')
     update.add_argument('--ref', help='a tag or commit to pin the one named pack to instead')
-    docs = commands.add_parser('docs', help="replace a pack's optional doc sets")
+    docs = commands.add_parser('docs', help="replace a pack's optional nested packs")
     docs.add_argument('name')
-    docs.add_argument('sets', help="comma-separated optional doc sets, or '' for none")
-    commands.add_parser('list', help='list the packs and their doc sets, marking the installed ones')
+    docs.add_argument('sets', help="comma-separated optional nested packs, or '' for none")
+    commands.add_parser('list', help='list the packs and their nested packs, marking the installed ones')
     args = parser.parse_args()
     repo = args.dir
     if not repo.is_dir():
         sys.exit(f'context-packs: {repo} is not a folder')
 
     found = region(repo)
-    packs, picked = apply(args, found)
+    packs = apply(args, found)
 
     with contextlib.ExitStack() as stack:
-        sources = [Source(p, fetch(repo, p, stack)) for p in packs]
+        folders = {p.name: fetch(repo, p, stack) for p in packs}
+        roots = {p.name: tree.load(folders[p.name], p) for p in packs}
         if args.command == 'list':
-            show(sources, picked)
+            show(packs, roots)
             return
 
         claude_md = repo / 'CLAUDE.md'
@@ -126,31 +134,20 @@ def main():
             sys.exit(f'context-packs: {claude_md} must be a symlink to AGENTS.md, so every agent reads the same rules. '
                      'Move its contents into AGENTS.md, delete it, then sync again.')
 
-        chosen = {}
-        for source in sources:
-            name = source.pack.name
-            unknown = sorted(n for n in picked[name] if n not in source.available())
-            if unknown:
-                sys.exit(f'context-packs: {name} has no doc set named {", ".join(unknown)}. '
-                         f'Available: {", ".join(source.available()) or "none"}. Choose from those with --docs.')
-            chosen[name] = source.installs(picked[name])
-        bodies = {s.pack.name: s.body(chosen[s.pack.name]) for s in sources}
-        starts = {s.pack.name: s.pack.start() for s in sources}
+        installed = {p.name: tree.installs(roots[p.name], p) for p in packs}
 
         for gone in {p.name for p in found.packs} - {p.name for p in packs}:
             if (repo / PACKS / gone).exists():
                 shutil.rmtree(repo / PACKS / gone)
         blocks = {HEADER: block(HEADER_START, HEADER_RULES)}
-        for source in sources:
-            if source.pack.local:
-                blocks[source.pack.name] = block(starts[source.pack.name], bodies[source.pack.name])
-                continue
-            synced = repo / source.pack.synced
-            if synced.exists():
-                shutil.rmtree(synced)
-            for name in chosen[source.pack.name]:
-                source.copy(name, synced)
-            blocks[source.pack.name] = block(starts[source.pack.name], bodies[source.pack.name], snapshot(synced))
+        for pack in packs:
+            root = roots[pack.name]
+            generated = repo / PACKS / pack.name
+            if generated.exists():
+                shutil.rmtree(generated)
+            tree.write(root, pack, installed[pack.name], folders[pack.name], repo)
+            blocks[pack.name] = block(pack.start(), tree.body(root, pack, installed[pack.name]),
+                                      snapshot(generated))
         if (repo / PACKS).is_dir() and not any((repo / PACKS).iterdir()):
             (repo / PACKS).rmdir()
         text = found.text[:found.start] + '\n'.join(blocks.values()) + found.text[found.end:]
@@ -158,7 +155,7 @@ def main():
         (repo / 'AGENTS.md').write_bytes(text.encode('utf-8'))
         if not linked:
             claude_md.symlink_to('AGENTS.md')
-        for line in report.changes(found, packs, chosen, blocks, created, linked):
+        for line in report.changes(found, packs, blocks, created, linked):
             print(line)
 
 

package/src/packs.py

@@ -1,30 +1,29 @@
 """Context packs: where each comes from, and its content once fetched."""
 from pathlib import Path
 import re
-import shutil
 import sys
 import tempfile
-from typing import NamedTuple, Optional
+from typing import NamedTuple, Optional, Tuple
 
 import origins
 
 PACKS = Path('docs/agents/packs')
 # A pack whose origin is the synced repo itself, read from its working tree.
 LOCAL = '.'
-FRONT = re.compile(r'---\n(.*?)\n---\n', re.DOTALL)
-TIERS = ('optional', 'required')
 
 
 class Pack(NamedTuple):
-    """Where a pack comes from: a folder in a git repo pinned to a commit, or a folder in the synced repo itself."""
+    """Where a pack comes from, a folder in a git repo pinned to a commit or a folder in the synced repo itself, and
+    the optional nested packs the repo picked from it."""
     name: str
     origin: str
     path: str
     ref: Optional[str]
+    docs: Tuple[str, ...] = ()
 
     def start(self):
         fields = ([f'from={self.origin}'] + [f'path={self.path}'] * bool(self.path)
-                  + [f'ref={self.ref}'] * bool(self.ref))
+                  + [f'ref={self.ref}'] * bool(self.ref) + [f'docs={",".join(self.docs)}'] * bool(self.docs))
         if any(re.search(r'\s', field) for field in fields):
             sys.exit(f'context-packs: the {self.name} pack\'s {" ".join(fields)} has whitespace, '
                      'which its marker can\'t hold.')
@@ -36,72 +35,11 @@ class Pack(NamedTuple):
 
     @property
     def synced(self):
-        """Where the pack's doc sets sit in the synced repo: copied into its own folder, or where they are for a
+        """Where the pack's docs sit in the synced repo: copied into its own folder, or where they are for a
         pack in that repo."""
         return Path(self.path) if self.local else PACKS / self.name
 
 
-class Source(NamedTuple):
-    """A pack's content, fetched into a folder holding its pack.md and doc sets."""
-    pack: Pack
-    folder: Path
-
-    def available(self):
-        """The pack's doc sets: each a folder holding an index.md, or a single .md file other than pack.md."""
-        if (self.folder / 'agents.md').is_file():
-            sys.exit(f'context-packs: {(Path(self.pack.path) / "agents.md").as_posix()} in {self.pack.origin} holds '
-                     'rules under the name packs used before 0.2.0. Rename it to pack.md in the pack, or run update '
-                     'to move to a version of the pack that has one.')
-        folders = {p.name for p in self.folder.iterdir() if p.is_dir() and not p.name.startswith('.')}
-        files = {p.stem for p in self.folder.glob('*.md') if p.name != 'pack.md'}
-        for name in sorted(folders & files):
-            sys.exit(f'context-packs: {self.pack.origin} has both {name}.md and {name}/ in '
-                     f'{self.pack.path or "its root"}, so the doc set {name} is ambiguous. Keep one.')
-        return sorted(folders | files)
-
-    def entry(self, name):
-        """A doc set's entry point, relative to the pack's folder."""
-        return Path(name, 'index.md') if (self.folder / name).is_dir() else Path(f'{name}.md')
-
-    def front(self, name):
-        """A doc set's front matter: when to read it, and whether every repo gets it."""
-        match = FRONT.match((self.folder / self.entry(name)).read_text(encoding='utf-8'))
-        pairs = [line.split(': ', 1) for line in match.group(1).split('\n')] if match else []
-        fields = dict(p for p in pairs if len(p) == 2)
-        if len(fields) != len(pairs) or 'when' not in fields or fields.get('tier', 'optional') not in TIERS:
-            where = (Path(self.pack.path) / self.entry(name)).as_posix()
-            sys.exit(f'context-packs: {where} in {self.pack.origin} must start with front matter saying when to '
-                     'read it, plus `tier: required` if every repo gets it:\n\n---\nwhen: Editing `**/*.ts`\n---')
-        return fields
-
-    def required(self):
-        return [n for n in self.available() if self.front(n).get('tier') == 'required']
-
-    def installs(self, picked):
-        """The doc sets the pack installs: all of a pack in the synced repo, else the picked and required ones."""
-        return self.available() if self.pack.local else sorted(set(picked) | set(self.required()))
-
-    def copy(self, name, synced):
-        if (self.folder / name).is_dir():
-            shutil.copytree(self.folder / name, synced / name)
-        else:
-            synced.mkdir(parents=True, exist_ok=True)
-            shutil.copy2(self.folder / f'{name}.md', synced / f'{name}.md')
-
-    def body(self, names):
-        rules_file = self.folder / 'pack.md'
-        rules = rules_file.read_text(encoding='utf-8') if rules_file.is_file() else ''
-        # The end marker has to start its own line, or the next sync can't find the block.
-        if rules and not rules.endswith('\n'):
-            rules += '\n'
-        if not names:
-            return rules
-        rows = ''.join(f'| {self.front(n)["when"]} | `{(self.pack.synced / self.entry(n)).as_posix()}` |\n'
-                       for n in names)
-        table = f'## {self.pack.name} context\n\n| When | Read |\n|---|---|\n{rows}'
-        return f'{rules}\n{table}' if rules else table
-
-
 def fetch(repo, pack, stack):
     """The folder holding pack's content, fetched at its ref unless it's in the synced repo."""
     if pack.origin == LOCAL:

package/src/report.py

@@ -17,10 +17,9 @@ def sets(names):
     return ', '.join(names) or 'none'
 
 
-def changes(found, after, chosen, blocks, created, linked):
+def changes(found, after, blocks, created, linked):
     """Lines describing what the sync did: whether it created AGENTS.md or found CLAUDE.md already linked to it, and
-    how the packs found in AGENTS.md became the packs after it, with chosen holding the doc sets each pack installs
-    and blocks the text the sync wrote for each."""
+    how the packs found in AGENTS.md became the packs after it, with blocks the text the sync wrote for each."""
     before = found.packs
     old = {p.name: p for p in before}
     new = {p.name for p in after}
@@ -29,12 +28,11 @@ def changes(found, after, chosen, blocks, created, linked):
     for pack in after:
         was = old.get(pack.name)
         if not was:
-            docs = chosen[pack.name]
-            lines.append(f'{pack.name}: added{at(pack)}' + f' (docs: {sets(docs)})' * bool(docs))
+            lines.append(f'{pack.name}: added{at(pack)}' + f' (docs: {sets(pack.docs)})' * bool(pack.docs))
         elif was.ref != pack.ref:
             lines.append(f'{pack.name}: {short(was.ref)} → {short(pack.ref)}')
-        elif not pack.local and found.installed[pack.name] != chosen[pack.name]:
-            lines.append(f'{pack.name}: doc sets {sets(found.installed[pack.name])} → {sets(chosen[pack.name])}')
+        elif was.docs != pack.docs:
+            lines.append(f'{pack.name}: nested packs {sets(was.docs)} → {sets(pack.docs)}')
         elif found.blocks[pack.name] != blocks[pack.name]:
             lines.append(f'{pack.name}: changed')
     lines += [f'{p.name}: removed' for p in before if p.name not in new]

package/src/tree.py

@@ -0,0 +1,176 @@
+"""A pack's content as a tree of packs: the installed pack's pack.md and docs, and each folder holding a pack.md of
+its own nested inside it. A folder without a pack.md only groups files, whose docs join the nearest pack's table."""
+from pathlib import Path
+import re
+import shutil
+import sys
+from typing import NamedTuple, Tuple
+
+from packs import PACKS
+
+FRONT = re.compile(r'---\n(.*?)\n---\n', re.DOTALL)
+
+
+class Doc(NamedTuple):
+    path: str
+    when: str
+
+
+class Node(NamedTuple):
+    """A pack in the tree. Its id is its folder relative to the installed pack's, '' for the installed pack itself,
+    and paths are relative to that folder too. Its files are every one it brings, docs included, but not those of
+    the packs nested in it."""
+    id: str
+    fields: dict
+    rules: str
+    docs: Tuple[Doc, ...]
+    files: Tuple[str, ...]
+    children: Tuple['Node', ...]
+
+    @property
+    def optional(self):
+        return 'optional' in self.fields
+
+    @property
+    def inline(self):
+        return 'inline' in self.fields
+
+    @property
+    def row(self):
+        """Whether the pack gets a row pointing at its index, rather than having its rules and table pasted into its
+        parent's, or into the block for the installed pack. Its parent is wherever it's installed, so a pack renders
+        the same installed on its own as inside another."""
+        return 'when' in self.fields and not self.inline
+
+    def nested(self):
+        """Every pack nested in this one, at any depth, parents before their children."""
+        for child in self.children:
+            yield child
+            yield from child.nested()
+
+
+def front(text, where, keys):
+    """text's front matter as fields, keeping only those named in keys, and the text after it."""
+    match = FRONT.match(text)
+    pairs = [line.split(': ', 1) for line in match.group(1).split('\n')] if match else []
+    fields = dict(p for p in pairs if len(p) == 2)
+    if len(fields) != len(pairs):
+        sys.exit(f'context-packs: {where} has front matter that isn\'t `key: value` lines.')
+    unknown = sorted(set(fields) - set(keys))
+    if unknown:
+        sys.exit(f'context-packs: {where} has front matter context-packs doesn\'t know: {", ".join(unknown)}. '
+                 'A doc takes only `when`, and a pack.md takes `when`, `optional` and `inline`. Remove it, or update '
+                 'context-packs if the pack needs a newer version.')
+    return fields, text[match.end():] if match else text
+
+
+def load(folder, pack, id=''):
+    """The pack in folder/id and the packs nested in it, with folder holding the pack fetched from pack."""
+    def where(path):
+        return f'{(Path(pack.path) / path).as_posix()} in {pack.origin}'
+
+    home = Path(id)
+    if not id and (folder / 'agents.md').is_file():
+        sys.exit(f'context-packs: {where("agents.md")} holds rules under the name packs used before 0.2.0. Rename it '
+                 'to pack.md in the pack, or run update to move to a version of the pack that has one.')
+    pack_md = folder / home / 'pack.md'
+    fields, rules = front(pack_md.read_text(encoding='utf-8'), where(home / 'pack.md'),
+                          ('when', 'optional', 'inline')) if pack_md.is_file() else ({}, '')
+    for key, without in (('optional', 'installed whenever its parent is'), ('inline', 'that gets a row')):
+        if fields.get(key, 'true') != 'true':
+            sys.exit(f'context-packs: {where(home / "pack.md")} has {key}: {fields[key]}, but {key} takes only '
+                     f'true. Leave it out for a pack {without}.')
+    # A nested pack's when is its row in its parent's table, or what list shows for an optional one, so only an
+    # inline pack that isn't optional goes without. The installed pack needs none: without one, it's pasted in.
+    if id and 'when' not in fields and not ('inline' in fields and 'optional' not in fields):
+        sys.exit(f'context-packs: {where(home / "pack.md")} must start with front matter saying when to read it, '
+                 'since it\'s nested in another pack:\n\n---\nwhen: Editing `web/**`\n---')
+    # The end marker has to start its own line, or the next sync can't find the block.
+    if rules and not rules.endswith('\n'):
+        rules += '\n'
+    docs, files, children = [], [], []
+
+    def walk(rel):
+        for entry in sorted((folder / rel).iterdir()):
+            path = rel / entry.name
+            if entry.name.startswith('.') or path == home / 'pack.md':
+                continue
+            if entry.is_dir() and (entry / 'pack.md').is_file():
+                twin = path.parent / f'{entry.name}.md'
+                if (folder / twin).is_file():
+                    sys.exit(f'context-packs: {where(path)} holds a pack.md and sits beside {where(twin)}, so its '
+                             f'index and that doc would both be {twin.as_posix()}. Rename one.')
+                children.append(load(folder, pack, path.as_posix()))
+            elif entry.is_dir():
+                walk(path)
+            else:
+                files.append(path.as_posix())
+                if entry.suffix == '.md':
+                    doc_fields, _ = front(entry.read_text(encoding='utf-8'), where(path), ('when',))
+                    if 'when' not in doc_fields:
+                        sys.exit(f'context-packs: {where(path)} must start with front matter saying when to read '
+                                 'it:\n\n---\nwhen: Editing `**/*.ts`\n---')
+                    docs.append(Doc(path.as_posix(), doc_fields['when']))
+
+    walk(home)
+    return Node(id, fields, rules, tuple(docs), tuple(files), tuple(children))
+
+
+def installs(root, pack):
+    """The ids of the packs nested in root that a sync installs: each one picked or above a picked one, and each
+    one not optional whose parent is installed."""
+    nested = {n.id for n in root.nested()}
+    unknown = sorted(set(pack.docs) - nested)
+    if unknown:
+        sys.exit(f'context-packs: {pack.name} has no nested pack named {", ".join(unknown)}. '
+                 f'Its nested packs: {", ".join(sorted(nested)) or "none"}. Choose from those with --docs.')
+    parts = [pick.split('/') for pick in pack.docs]
+    wanted = {'/'.join(p[:i]) for p in parts for i in range(1, len(p) + 1)}
+
+    def visit(node):
+        for child in node.children:
+            if not child.optional or child.id in wanted:
+                yield child.id
+                yield from visit(child)
+    return set(visit(root))
+
+
+def index(node, pack):
+    """Where a pack's generated index sits: pack.md for the installed pack, since no doc can have that name."""
+    return PACKS / pack.name / f'{node.id or "pack"}.md'
+
+
+def table(title, rows):
+    """A table of (when, path) rows under its heading, or nothing without rows."""
+    return (f'## {title} context\n\n| When | Read |\n|---|---|\n'
+            + ''.join(f'| {when} | `{path.as_posix()}` |\n' for when, path in rows)) if rows else ''
+
+
+def render(node, pack, installed):
+    """The node's rules, then its table: a row for each of its docs and for each installed pack nested in it that
+    gets one. The others are rendered the same way after it."""
+    children = [c for c in node.children if c.id in installed]
+    rows = sorted([(d.path[:-len('.md')], d.when, pack.synced / d.path) for d in node.docs]
+                  + [(c.id, c.fields['when'], index(c, pack)) for c in children if c.row])
+    title = f'{pack.name}/{node.id}' if node.id else pack.name
+    pasted = [render(c, pack, installed) for c in children if not c.row]
+    return '\n'.join(part for part in (node.rules, table(title, [r[1:] for r in rows]), *pasted) if part)
+
+
+def body(root, pack, installed):
+    """The installed pack's block: a row pointing at its index if it gets one, else its rules and table."""
+    return table(pack.name, [(root.fields['when'], index(root, pack))]) if root.row else render(root, pack, installed)
+
+
+def write(root, pack, installed, source, repo):
+    """Copy the installed packs' files from source into repo, unless the pack is in repo already, and write the
+    index of each installed pack that gets a row."""
+    for node in [root] + [n for n in root.nested() if n.id in installed]:
+        copies = [] if pack.local else [(source / path, repo / pack.synced / path) for path in node.files]
+        for origin, target in copies:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(origin, target)
+        if node.row:
+            target = repo / index(node, pack)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(render(node, pack, installed), encoding='utf-8')