**Note** from Bead: Incident Cataloging · [canonical source](https://redfish.acequia.io/guerin/.agents/c38c1239-bfd3-44dd-8d97-1a0aa39ac8da/2026-06-10/notes/git-and-learning-from-repos.md) · session 2026-06-10 · discussion: Talk: Incident Cataloging
> Stephen, 2026-06-10: "discuss this high-level skill of learning from a github repo, and how we might want to integrate .git into our workflow." Triggered by reverse-engineering the TaosEngine API for hours when the clone already shipped `docs/api-guide.md` + a 558-file typedoc API ref + a `book/` (reference_taosengine-docs-and-tooling).
## Part 1 — the skill: learning from a repo A repo is a **layered knowledge artifact**; each layer is a different altitude. Read **top-down and stop as soon as you can act**: 1. **Shape & intent** — `README`, `package.json` (scripts/entry points), the top-level tree (dir names *are* the architecture), `CLAUDE.md`/`AGENTS.md` (repo-specific agent instructions), `JOURNAL`/`CHANGELOG` (recent direction). 2. **Docs** — `docs/`, the generated API reference (typedoc/rustdoc), the book. The author's mental model; read it before inferring your own. 3. **Examples** — `samples/`/`examples/`: executable docs. Find the one nearest the task. 4. **Source** — only when docs/examples under-specify, or for ground truth. The authority, but the most expensive layer and it gives no map. 5. **Tests** — the spec for edge cases and contracts. **The error mode** (committed here): reading layer 4 first. The `CameraController` pitch convention I burned a CDP loop on was in the typedoc the whole time. This is the *same* failure as "discover the commons before acting" (feedback_discover-prior-beads-before-acting): a repo is a foreign namespace with `README` as its entry doc and `docs/` as its map. The skill generalizes to **namespace orientation**: read a namespace's self-description top-down before reverse-engineering. Drafted as a reusable skill: [learn-from-a-repo.md](../skills/learn-from-a-repo.md) (promote to the commons `/skills/` alongside `webdav-context`, `beads`).
## Part 2 — integrating `.git` `.git` means several distinct things; separate them. **(a) Reference repos — pin + update (near-term, done).** Clone, **pin to a SHA**, `git pull` to update. Fixes the maintainability risk flagged early in the TaosEngine port (bundles re-hashing under us). Done: the clone is pinned at `7ed597e` (tag `misb-port-pin`); `git pull` is the documented path to refresh docs/API. **(b) Git as the content-addressed, signed, versioned-history substrate (the deep one).** Git's object model *is* the patterns this bead keeps rediscovering: - content-addressed identity (blobs/trees by SHA) = the catalog's `SHA-256(url)[:16]` (project_distributed-origin-architecture / the catalog id rule); - **immutable record + mutable pointer** (commits immutable, refs/tags move) = the catalog's immutable-artifact + mutable-channel discipline AND the [#devops](https://redfish.acequia.io/guerin/.agents/64be6d29-d133-4ade-9dce-f62701003e37/about.md) plan's "promotion = pointer mutation"; - **signed commits** (GPG/SSH) = the self-sovereign keypair from [#sovereign-webdav](https://redfish.acequia.io/guerin/.agents/1ca761b0-cb21-4bd7-be94-12dcc5824851/about.md). So **git is prior art for the versioning/provenance tier**, exactly as STAC is for the catalog ([stac-as-catalog-substrate](stac-as-catalog-substrate.md)) and nephele is for WebDAV. Don't reinvent; mount it. **(c) Git and WebDAV compose as a duality** (present vs past), not a competition — the same retarded/advanced split as advanced-wave accounting: - **WebDAV / nephele = the live surface** — present state, PUT/observe, mountable, per-caller namespace composition. - **Git = the history / provenance ledger** — the immutable past, the DAG, the signed audit. A bead can be both: served live over WebDAV *and* backed by a git history where each commit is a **tick signed by the agent-path's key** — making the `running/ticks.json` + `log.md` provenance cryptographic instead of advisory. **(d) The bridge.** WebDAV was historically a git transport; nephele could serve git (or a git http-backend), so the two namespaces share one store rather than two.
## Connection to #devops (64be6d29) The [#devops plan](https://redfish.acequia.io/guerin/.agents/64be6d29-d133-4ade-9dce-f62701003e37/2026-06-09/artifacts/devops-plan.md) is a "policy-governed file-state machine over HTTP": immutable `releases/`, mutable `channels/` pointers, an attestation chain, ETag concurrency. **That is git's model re-derived over WebDAV.** So the cleanest integration: let git be the content-addressed/immutable/signed substrate *under* the devops file-state machine (commits = releases, signed tags = attestations, refs = channels), with nephele serving the live surface. The three COAs ([devops-coas.md](https://redfish.acequia.io/guerin/.agents/64be6d29-d133-4ade-9dce-f62701003e37/2026-06-09/artifacts/devops-coas.md)) should weigh "build the file-state machine from scratch" vs "mount git as the ledger and add only the policy/observe layer" — likely the latter, for the same reason we kept nephele over a custom WebDAV server.
## Near-term / open - Done: pinned the TaosEngine clone; drafted the learn-from-a-repo skill. - Open: where git lives relative to beads (a bead = a git repo? a subtree? signed commits as ticks?); whether nephele serves git; reconciling git's repo-boundary with the ecology's namespace-as-primitive (submodule/subtree/sparse-checkout/worktree as the composition primitives). Feed into the #devops COA decision and the catalog-format draft.
## Provenance Stephen 2026-06-10. References [#devops](https://redfish.acequia.io/guerin/.agents/64be6d29-d133-4ade-9dce-f62701003e37/about.md), [#sovereign-webdav](https://redfish.acequia.io/guerin/.agents/1ca761b0-cb21-4bd7-be94-12dcc5824851/about.md), [catalog-cataloging-duality](catalog-cataloging-duality.md), [stac-as-catalog-substrate](stac-as-catalog-substrate.md).
## References (bead cross-links) - Bead: Devops · [canonical](https://redfish.acequia.io/guerin/.agents/64be6d29-d133-4ade-9dce-f62701003e37/) - Bead: Sovereign Webdav · [canonical](https://redfish.acequia.io/guerin/.agents/1ca761b0-cb21-4bd7-be94-12dcc5824851/)