How to share notes, issues, and docs across repositories

Start with sibling repositories named handbook and project. The handbook has an initialized zettel store with the note pzya-retry-with-jitter. The project has initialized zettel, tisket, and diataxis stores.

Declare the handbook

In project, create stores.yml beside the tool marker files:

format: 2
stores:
  - alias: handbook
    path: ../handbook

List the note stores from project:

zettel store list

The list shows the local store and the declared handbook:

(this store)  /path/to/project  0 note(s)
handbook  ../handbook  1 note(s)

Link to a note in the handbook

Use the handbook note’s own prefix in place of pzya:

zettel note create "Client retries on 503" -t retries -p human -b "Follows [[handbook:pzya]]."
zettel check
zettel backlinks handbook:pzya

The check prints no problems found. The backlinks command lists the local note, with its generated prefix:

mfq3-client-retries-on-503  Client retries on 503

A body link uses the alias and note prefix, as in the command above. For a frontmatter link, use handbook:pzya in links:. For a provenance citation, use citation:handbook:pzya in the marker.

If a link names a missing note, zettel check exits 1. It prints 1 problem(s): with the note and a target such as → handbook:zzzz [body].

Check what each tool sees

List the same declarations through the other tools:

tisket store list
diataxis store list

Their handbook rows report:

handbook  ../handbook  0 issue(s)
handbook  ../handbook  0 page(s)

The handbook has notes but no tracker or docs. One stores.yml serves every tool beside it; almanac reads the file for skill libraries too.

Use backlinks and check to follow declared stores. zettel search and zettel read read only the local store.

Make declarations available to other clones

For a repository other people clone, set top-level shared: true in stores.yml. Run the check:

zettel check

With shared: true, the check exits 1 for any path that leaves the repository, such as ../handbook. Declare such a store by git URL before sharing the repository.

For remote stores, replace path with git: <https url> and an optional rev, or blob: <https prefix with an index.txt>. Declare HTTPS sources; SSH URLs are refused.

Run <tool> store sync for each tool that needs the remote store. It fetches remote stores into a local cache and is the only store command that reaches the network. With only path stores, it reports that no remote stores are declared.

Declare repositories in the personal store that annotates them.

Zettel’s composed stores describe this direction. Almanac composition covers skill libraries.