Resources
1Install
npx skillscat add commontoolsinc/labs/topics Install via the SkillsCat registry.
Topics on Estuary
Topics is the team's minimal issue tracker: a board piece holding Topic pieces
on Estuary, driven through cf. This file is the map. Each file underreferences/ carries the detail for one part of the work and is the thing to
read once you are doing that part. skills/cf/SKILL.md is the general CLI
surface; the pattern's canonical semantics arepackages/patterns/topics/README.md, and its verb contractspackages/patterns/topics/main.tsx and packages/patterns/topics/topic.tsx.
Where, and as whom
Run from inside the Labs checkout. Every command in this skill and its
references is spelled deno task cf, which runs that checkout's CLI from any
directory in it and needs nothing on PATH; skills/cf/SKILL.md covers the other
routes. Shell state rarely survives between an agent's tool calls, so set these
in the same invocation as the command that needs them:
export CF_API_URL='https://estuary.saga-castor.ts.net'
export CF_SPACE='topics-dev-476ea34f'
export TOPICS_BOARD='/of:fid1:jtdD-DSmuGrLGSt_6sJ3DS_7jmerrkKTEnW3fZV9e34'
export CF_IDENTITY="${CF_IDENTITY:-$HOME/.config/commonfabric/identity.key}"The key is the team's per-user default at that path, the same one your human
user holds; an already-set CF_IDENTITY is the explicit override. When cf
reports the keyfile missing or unreadable, stop and ask the human to provision
that default or export the correct path: the check belongs to cf, so the shell
never touches the key. Do not search for keys, mint an agent key, use another
human's key, or use the publicly derivable implicit trust identity, and never
print or inspect key material; deno task cf id did "$CF_IDENTITY" gives the
public DID when one is needed.
Every authored-content mutation carries agentName in the same event: one
stable agent name, and no second signature in titles, labels, bodies, or
comments. Fabric retains the human principal behind the key; Topics stores the
agent name as content attribution. mention and unmention record only a
reference edge and take no agentName.
What holds throughout
- Reading Topics starts with the projected board
indexinreferences/reading.md.piece describedocuments a piece's readable fields
and operations;piece verbslists operations to call. A verb listing says
nothing about how much readable data the piece holds. - The running piece is authoritative. Estuary is the Topics production
deployment and routinely trails the checkout; commit distance alone does not
establish incompatibility or explain a failure. Discover the piece's contract
before mutating. Its pinned pattern reference and the server commit reported
by/api/metaidentify different things;references/verbs.mdcovers both. - Discovery is bounded: survey the projected
index, expand one Topic at a
time, and take an emitted$linkunchanged. - A call's envelope, or its absence, is an observation and not proof of durable
state. One invocation session per run, one invocation id per logical mutation,
a read-back after every write, and no retry on the strength of a timeout,
which is how one Topic becomes two. - The body is the living document, replaced whole; comments are append-only,
point-in-time progress; every relevant pull request is anaddLinkwithkind: "pr"; relationships between Topics are references, never pasted fids. - Changing the board's or a Topic's pattern source is a production migration
over team-critical data, held behind the rehearsal and authorization rules inreferences/pattern-updates.md.
The detail, by task
| Read | When you are |
|---|---|
references/reading.md |
surveying the board or reading a Topic: the index, addresses and how to compare them, durable inputs against stepped results |
references/verbs.md |
discovering fields and operations, choosing a verb, identifying the deployed contract, retraction and by-reference verbs |
references/naming.md |
citing or resolving a Topic by its number, top/42, and what the deployment carries |
references/mutating.md |
creating a Topic and recovering its address, the observation asymmetry, the Topic verbs, references between Topics, the editorial conventions |
references/pattern-updates.md |
changing pattern source: setsrc rehearsal, --root, team authorization |
references/namespace-backfill.md |
naming the Topics filed before the namespace: the operator procedure and its traps |