context-packs 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Jewell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# context-packs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sync shared agent rules and docs into each repo's `AGENTS.md`.
+
+A context pack is a folder in a git repo holding rules every agent session should see, and docs that agents read only for some kinds of work. `context-packs` copies the packs a repo installs into that repo, pinned to a tag or commit, so Claude Code, Codex and any other agent that reads `AGENTS.md` get the same rules. That includes cloud sessions and fresh clones, which see only what's committed.
+
+## Install
+
+Run it with npx:
+
+```bash
+npx context-packs <command>
+```
+
+It syncs the current folder. Pass `--dir <folder>` before the command to sync another.
+
+It needs `git`, Node 18 or later, and Python 3.9 or later. On macOS, the Xcode command line tools that provide `git` provide Python too.
+
+This repo is also a Claude Code plugin with a `/context-packs` skill, which runs the commands for you. Add it to a plugin marketplace, or install just the skill for Claude Code and Codex with `npx skills add mjewell/context-packs -g -a claude-code -a codex`.
+
+## Use it
+
+```bash
+npx context-packs add team-rules https://github.com/acme/agent-rules.git --path context
+```
+
+That writes two blocks into `AGENTS.md`: a header block explaining context packs, and one for the pack. It also copies the pack's doc sets into `docs/agents/packs/team-rules/`, and creates `CLAUDE.md` as a symlink to `AGENTS.md`, so Claude Code reads the same file. Commit the result.
+
+If `AGENTS.md` already exists, the first run prints two marker lines instead. Paste them where the shared rules should go, after the intro and before the project-specific sections, and run it again.
+
+| 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` |
+| `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 |
+
+A folder that holds several repos without being one can be synced too, so sessions started there get the rules. A Claude Code session started inside one of those repos then loads both copies, since Claude Code reads `CLAUDE.md` from the folders above it as well.
+
+### Pinning and updates
+
+Each pack's start marker records where it comes from and where it's pinned:
+
+```markdown
+<!-- context-packs:start team-rules from=https://github.com/acme/agent-rules.git path=context ref=v1.2.0 -->
+```
+
+`--ref` takes a tag or a commit, never a branch, since a branch moves. `update` moves a pack along what it's pinned to:
+
+- **A commit** moves to the tip of the origin's default branch.
+- **A release tag**, meaning a prefix followed by dot-separated numbers such as `v1.2.0` or `acme-v3`, moves to the newest release with the same prefix. Pre-releases like `v2.0.0-rc1` are skipped.
+- **Any other tag** stays put.
+
+The sync fetches origins into `~/.cache/context-packs/` using your own git credentials, so private repos work.
+
+A pack can also live in the repo it's synced into: `add <name> . --path <folder>` reads it from the working tree, with no ref. Its table points at the docs where they are instead of copying them, and it installs every doc set it has.
+
+That's the way to keep a repo's own context docs. Put each one in `docs/agents/project/` with a `when:` line, run `add project . --path docs/agents/project` once, and resync after adding a doc or changing its `when:`. The table in `AGENTS.md` stays generated from the docs.
+
+### Edits stay upstream
+
+Each block ends with a hash covering its text and its docs folder. If either was edited in the repo, the sync stops without changing anything and says what to fix. Change a pack in its origin, then update.
+
+## Write a pack
+
+A pack is a folder holding an optional `agents.md` and any number of doc sets. A doc set is a single `.md` file, or a folder whose `index.md` links to its other files:
+
+```text
+context/
+├── agents.md           # rules pasted into the pack's block
+├── testing.md          # a doc set in one file
+└── typescript/
+    ├── index.md        # a doc set's entry point
+    └── react.md        # other files, linked from index.md
+```
+
+Each doc set's entry point starts with front matter saying when to read it:
+
+```markdown
+---
+when: Writing or changing tests, or fixing a bug
+tier: required
+---
+```
+
+The pack's block lists its installed doc sets in a table that agents check before starting work. `tier: required` installs the set in every repo that installs the pack. Leave `tier` out for an optional set, which each repo chooses with `--docs` or `docs`.
+
+Keep `agents.md` small, since every session loads it, and put anything needed only for some work in a doc set. agy stops reading `AGENTS.md` after 24 KB.
+
+## Tests
+
+```bash
+python3 -m unittest discover tests
+```

package/bin/context-packs.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// Runs the Python CLI bundled with this package, passing its arguments, output and exit code through.
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+const cli = path.join(__dirname, '..', 'src', 'cli.py');
+const result = spawnSync('python3', [cli, ...process.argv.slice(2)], { stdio: 'inherit' });
+if (result.error) {
+  console.error(`context-packs: couldn't run python3 (${result.error.message}). Install Python 3.9 or later.`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "context-packs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Sync shared agent rules and docs into each repo's AGENTS.md",
+  "license": "MIT",
+  "bin": {
+    "context-packs": "bin/context-packs.js"
+  },
+  "files": [
+    "bin",
+    "src/*.py"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjewell/context-packs.git"
+  }
+}

package/src/blocks.py

@@ -0,0 +1,116 @@
+"""The context-packs blocks in AGENTS.md, and the doc sets each pack installed beside them."""
+import hashlib
+import re
+import sys
+from typing import Dict, List, NamedTuple
+
+from packs import LOCAL, PACKS, Pack
+
+HEADER = 'header'
+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")
+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."""
+    text: str
+    start: int
+    end: int
+    blocks: Dict[str, str]
+    packs: List[Pack]
+    installed: Dict[str, List[str]]
+
+
+def digest(body, docs=b''):
+    return hashlib.sha256(body.encode() + docs).hexdigest()[:12]
+
+
+def block(start, body, docs=b''):
+    return f'{start}{body}<!-- context-packs:end sha256:{digest(body, docs)} -->\n'
+
+
+def snapshot(folder):
+    """The synced docs' paths and contents, which the block's hash covers so edits to them are caught too."""
+    if not folder.is_dir():
+        return b''
+    return b''.join(f'{p.relative_to(folder).as_posix()}\0'.encode() + p.read_bytes() + b'\0'
+                    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
+            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. '
+                 'Fix the marker, then sync again.')
+    return Pack(name, origin, fields.get('path', ''), fields.get('ref'))
+
+
+def region(repo):
+    """AGENTS.md's context-packs blocks, after checking that nothing in them was edited since the last sync."""
+    agents_md = repo / 'AGENTS.md'
+    if agents_md.is_symlink():
+        sys.exit(f'context-packs: {agents_md} is a symlink, and the sync would write through it. '
+                 'Delete it, then sync again to get a real file.')
+    # Bytes, so Python doesn't quietly turn the repo's CRLF line endings into LF.
+    text = agents_md.read_bytes().decode('utf-8') if agents_md.exists() else block(HEADER_START, '')
+    if '\r' in text:
+        sys.exit(f'context-packs: {agents_md} has CRLF line endings. Convert it to LF, then sync again.')
+    blocks = list(BLOCK.finditer(text))
+    if not blocks:
+        sys.exit(f'context-packs: {agents_md} has no context-packs blocks. '
+                 f'Add these two lines where the shared rules should go, then sync again:\n\n{block(HEADER_START, "")}')
+    names = [match.group(1) for match in blocks]
+    if names[0] != HEADER:
+        sys.exit(f'context-packs: {agents_md}: the context-packs blocks must start with the header block. '
+                 f'Add these two lines before them, then sync again:\n\n{block(HEADER_START, "")}')
+    for name in sorted({n for n in names if names.count(n) > 1}):
+        sys.exit(f'context-packs: {agents_md} has more than one {name} block. Delete all but one, then sync again.')
+    for before, after in zip(blocks, blocks[1:]):
+        if text[before.end():after.start()] != '\n':
+            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}
+    for match in blocks:
+        name, _, synced, sha = match.groups()
+        if digest(synced, snapshot(repo / PACKS / name) if name in copied else b'') != 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)

package/src/cli.py

@@ -0,0 +1,166 @@
+#!/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>/."""
+import argparse
+import contextlib
+import os
+from pathlib import Path
+import re
+import shutil
+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
+
+
+def sets(text):
+    return {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."""
+    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. '
+                     'Use letters, digits, dots, dashes and underscores.')
+        if args.name in names:
+            sys.exit(f'context-packs: {args.dir} already has a pack named {args.name}.')
+        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)
+    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:
+        sys.exit(f'context-packs: {args.dir} has no pack named {", ".join(unknown)}. '
+                 f'Its packs: {", ".join(names) or "none"}.')
+    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)
+    if args.command == 'update':
+        if args.ref and len(named) != 1:
+            sys.exit('context-packs: --ref pins one pack, so name exactly one.')
+        for i, pack in enumerate(packs):
+            if pack.name not in (named or names):
+                continue
+            if pack.origin == LOCAL:
+                if args.ref:
+                    sys.exit(f'context-packs: the {pack.name} pack syncs from this repo\'s working tree, '
+                             'so it takes no --ref.')
+                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
+        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"]}')
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='context-packs', description=__doc__)
+    parser.add_argument('--dir', type=Path, default=Path.cwd(),
+                        help='the folder to sync, if not the current one')
+    commands = parser.add_subparsers(dest='command', metavar='command',
+                                     description='leave out the command to resync every pack at its pinned ref')
+    add = commands.add_parser('add', help="install a pack, pinned to its origin's latest commit or to --ref")
+    add.add_argument('name', help='what to call the pack in AGENTS.md and docs/agents/packs/')
+    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')
+    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 '
+                                                "origin's default branch, one pinned to a release tag to the newest "
+                                                '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.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')
+    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)
+
+    with contextlib.ExitStack() as stack:
+        sources = [Source(p, fetch(repo, p, stack)) for p in packs]
+        if args.command == 'list':
+            show(sources, picked)
+            return
+
+        claude_md = repo / 'CLAUDE.md'
+        linked = claude_md.is_symlink() and os.readlink(claude_md) == 'AGENTS.md'
+        if not linked and os.path.lexists(claude_md):
+            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}
+
+        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))
+        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:]
+        created = not (repo / 'AGENTS.md').exists()
+        (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):
+            print(line)
+
+
+if __name__ == '__main__':
+    main()

package/src/origins.py

@@ -0,0 +1,100 @@
+"""Fetch context packs from their git origins, through a cache of bare clones that every sync shares."""
+import io
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tarfile
+
+COMMIT = re.compile(r'[0-9a-f]{40}')
+# A release tag: a series prefix, then only dot-separated numbers, such as v1.2.0 or acme-v3.
+RELEASE = re.compile(r'(\D*)(\d+(?:\.\d+)*)')
+
+
+def git(*args):
+    result = subprocess.run(['git', *args], capture_output=True)
+    if result.returncode != 0:
+        sys.exit(f'context-packs: git {" ".join(args)} failed:\n{result.stderr.decode().strip()}')
+    return result.stdout.decode().strip()
+
+
+def clone(url):
+    """The cached bare clone of url, cloning it the first time."""
+    cache = Path(os.environ.get('XDG_CACHE_HOME') or Path.home() / '.cache') / 'context-packs'
+    folder = cache / re.sub(r'[^A-Za-z0-9._-]+', '_', url)
+    if not folder.exists():
+        cache.mkdir(parents=True, exist_ok=True)
+        git('clone', '--quiet', '--bare', url, str(folder))
+    return folder
+
+
+def commit(folder, ref):
+    """The full commit ref names in the clone at folder, or None if it names none."""
+    result = subprocess.run(['git', '--git-dir', str(folder), 'rev-parse', '--verify', '--quiet', f'{ref}^{{commit}}'],
+                            capture_output=True)
+    return result.stdout.decode().strip() if result.returncode == 0 else None
+
+
+def fetched(url, ref):
+    """The cached clone of url, fetched until it has ref, or None if the origin has no such commit or tag."""
+    folder = clone(url)
+    if not commit(folder, ref):
+        git('--git-dir', str(folder), 'fetch', '--quiet', 'origin', '+refs/heads/*:refs/heads/*',
+            '+refs/tags/*:refs/tags/*')
+    return folder if commit(folder, ref) else None
+
+
+def remote(url, kind):
+    """url's tags or branches, by name."""
+    lines = git('ls-remote', f'--{kind}', '--refs', url).splitlines()
+    return {ref.split('/', 2)[2]: sha for sha, ref in (line.split('\t') for line in lines)}
+
+
+def tip(url):
+    """The commit at the tip of url's default branch."""
+    head = git('ls-remote', url, 'HEAD').split()
+    if not head:
+        sys.exit(f'context-packs: {url} has no default branch to pin to.')
+    return head[0]
+
+
+def pin(url, ref):
+    """ref as a pack's marker holds it: a tag stays a tag, and a commit becomes its full hash."""
+    if ref in remote(url, 'tags'):
+        return ref
+    if ref in remote(url, 'heads'):
+        sys.exit(f'context-packs: {ref} is a branch in {url}, and a branch moves. Pin to a tag or a commit, '
+                 'or leave out --ref to follow the default branch on update.')
+    folder = fetched(url, ref)
+    if not folder:
+        sys.exit(f'context-packs: {url} has no tag or commit {ref}.')
+    return commit(folder, ref)
+
+
+def latest(url, ref):
+    """Where an update moves a pack pinned to ref: a commit to the tip of the default branch, a release tag to the
+    newest release in its series, and any other tag nowhere."""
+    if COMMIT.fullmatch(ref):
+        return tip(url)
+    current = RELEASE.fullmatch(ref)
+    if not current:
+        return ref
+    releases = [(tuple(map(int, match.group(2).split('.'))), name)
+                for name in [ref, *remote(url, 'tags')]
+                for match in [RELEASE.fullmatch(name)] if match and match.group(1) == current.group(1)]
+    return max(releases)[1]
+
+
+def extract(url, ref, path, into):
+    """Write the folder at path in url, as of ref, into the folder into, and return where it landed."""
+    folder = fetched(url, ref)
+    if not folder:
+        sys.exit(f'context-packs: {url} has no tag or commit {ref}. Pin the pack to one that exists, then sync again.')
+    archive = subprocess.run(['git', '--git-dir', str(folder), 'archive', '--format=tar', ref, '--', path or '.'],
+                             capture_output=True)
+    if archive.returncode != 0:
+        sys.exit(f'context-packs: {url} has no folder {path} at {ref}:\n{archive.stderr.decode().strip()}')
+    with tarfile.open(fileobj=io.BytesIO(archive.stdout)) as tar:
+        tar.extractall(into)
+    return into / path

package/src/packs.py

@@ -0,0 +1,109 @@
+"""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
+
+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."""
+    name: str
+    origin: str
+    path: str
+    ref: Optional[str]
+
+    def start(self):
+        fields = ([f'from={self.origin}'] + [f'path={self.path}'] * bool(self.path)
+                  + [f'ref={self.ref}'] * bool(self.ref))
+        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.')
+        return f'<!-- context-packs:start {" ".join([self.name, *fields])} -->\n'
+
+    @property
+    def local(self):
+        return self.origin == LOCAL
+
+    @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
+        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 agents.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 agents.md."""
+        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 != 'agents.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 / 'agents.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:
+        folder = repo / pack.path
+        if not folder.is_dir():
+            sys.exit(f'context-packs: the {pack.name} pack\'s folder {pack.path} isn\'t in {repo}.')
+        return folder
+    into = Path(stack.enter_context(tempfile.TemporaryDirectory(prefix='context-packs-')))
+    return origins.extract(pack.origin, pack.ref, pack.path, into)

package/src/report.py

@@ -0,0 +1,43 @@
+"""What a sync changed, in lines for the person who ran it."""
+from blocks import HEADER
+from origins import COMMIT
+
+
+def short(ref):
+    """ref as git shows it: a commit abbreviated, a tag in full."""
+    return ref[:7] if COMMIT.fullmatch(ref) else ref
+
+
+def at(pack):
+    """Where the pack is pinned, or nothing for one that syncs from the repo's working tree."""
+    return f' @ {short(pack.ref)}' if pack.ref else ''
+
+
+def sets(names):
+    return ', '.join(names) or 'none'
+
+
+def changes(found, after, chosen, 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."""
+    before = found.packs
+    old = {p.name: p for p in before}
+    new = {p.name for p in after}
+    lines = (['Created AGENTS.md'] * created + ['Linked CLAUDE.md to AGENTS.md'] * (not linked)
+             + ['Updated the header block'] * (not created and found.blocks[HEADER] != blocks[HEADER]))
+    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))
+        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 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]
+    if lines:
+        return lines
+    return [f'Nothing changed: {", ".join(p.name + at(p) for p in after) or "no packs installed"}']