sessionmemory 0.7.0__tar.gz → 0.8.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/PKG-INFO +52 -3
  2. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/README.md +51 -2
  3. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/pyproject.toml +1 -1
  4. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/pyproject.toml.orig +1 -1
  5. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/new.py +24 -1
  6. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/bootstrap.py +2 -1
  7. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/field.py +32 -2
  8. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/inject.py +34 -1
  9. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/paths.py +10 -3
  10. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/__init__.py +0 -0
  11. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/cli.py +0 -0
  12. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/__init__.py +0 -0
  13. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/_common.py +0 -0
  14. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/delete.py +0 -0
  15. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/doctor.py +0 -0
  16. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/export.py +0 -0
  17. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/init.py +0 -0
  18. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/inject.py +0 -0
  19. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/log.py +0 -0
  20. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/project.py +0 -0
  21. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/reindex.py +0 -0
  22. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/commands/search.py +0 -0
  23. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/__init__.py +0 -0
  24. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/atomic.py +0 -0
  25. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/backlog.py +0 -0
  26. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/config.py +0 -0
  27. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/doctor.py +0 -0
  28. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/embed.py +0 -0
  29. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/export.py +0 -0
  30. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  31. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  32. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  33. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/ids.py +0 -0
  34. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/log.py +0 -0
  35. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/registry.py +0 -0
  36. {sessionmemory-0.7.0 → sessionmemory-0.8.0}/src/sessionmemory/lib/resolve.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: sessionmemory
3
- Version: 0.7.0
3
+ Version: 0.8.0
4
4
  Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
5
  Author: Nathaniel Landau
6
6
  Author-email: Nathaniel Landau <github@natelandau.com>
@@ -194,7 +194,8 @@ and the summary is what a search result shows. Both state the fact and not the t
194
194
  ## What a session sees
195
195
 
196
196
  `sessionmemory inject` prints the block a session starts with. This is the block for a
197
- project holding four learnings, one spec, one plan, and two open backlog items:
197
+ project holding four learnings, one spec, one plan, one reference doc, and two open
198
+ backlog items:
198
199
 
199
200
  ```
200
201
  ## Using this vault
@@ -202,7 +203,8 @@ project holding four learnings, one spec, one plan, and two open backlog items:
202
203
  Durable memory for this project lives in a vault of markdown pages. Nothing below is
203
204
  loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
204
205
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
205
- `specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
206
+ `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
207
+ and Edit.
206
208
  `sessionmemory project --json` prints every path.
207
209
 
208
210
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
@@ -229,6 +231,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
229
231
  configuring a service, rotating a credential, or recovering from an outage.
230
232
  Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
231
233
  which prints its path, never in another folder or the repository.
234
+ - Reference: `reference/` holds this project's private docs, such as hosting
235
+ settings, where each credential lives, or a data dictionary, kept out of its
236
+ repository. Any it holds are listed below; before working in an area, read the one
237
+ whose name matches. Keep a doc current by editing it in place. Create one with
238
+ `sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
239
+ documentation stays in the repository.
232
240
  - Learnings are captured at session end, not by you mid-session. When the user asks
233
241
  to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
234
242
  creates the page and prints the path to write prose into. Title and summary state
@@ -241,6 +249,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
241
249
  - Stripe retries a webhook for 72 hours, so the handler must be idempotent
242
250
  - The nightly reconciliation job must start after the 02:00 bank feed
243
251
 
252
+ ## Reference docs
253
+
254
+ reference/hosting.md
255
+
244
256
  ## Open work
245
257
 
246
258
  2 open backlog items
@@ -250,6 +262,43 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
250
262
  A page body never enters that block, so its cost grows with the number of pages and not
251
263
  with their length. The titles say what exists. `sessionmemory search` returns what they say.
252
264
 
265
+ ## Add rules to your CLAUDE.md
266
+
267
+ The guidance block above tells a session how to read and write the vault. It does not
268
+ control where other skills and plugins write their files. A planning skill writes its
269
+ plans and specs to the path it chose for itself, often under the repository's `docs/`.
270
+ Rules in a `CLAUDE.md` file send that work to the vault.
271
+
272
+ Put the rules in your user file, `~/.claude/CLAUDE.md`, so that they apply in every
273
+ registered project. A project `CLAUDE.md` is committed with the code. Other contributors
274
+ read it, and they have no access to your vault.
275
+
276
+ Copy this block into the file:
277
+
278
+ ```markdown
279
+ ## Session memory
280
+
281
+ - Write every plan, spec, and design document into the sessionmemory vault, including
282
+ the ones a skill or plugin generates. Create them with
283
+ `sessionmemory new spec --title "..." --cwd .` and
284
+ `sessionmemory new plan --title "..." --cwd .`. Never write them under the
285
+ repository's `docs/`, which holds public documentation.
286
+ - Write every runbook (a step-by-step procedure to follow by hand) with
287
+ `sessionmemory new runbook --title "..." --cwd .`.
288
+ - Keep documentation that describes the code and is safe to publish in the repository.
289
+ Put private documentation about a project, such as hosting settings or where each
290
+ credential lives, in the vault with `sessionmemory new reference --title "..." --cwd .`,
291
+ and edit that file in place afterward.
292
+ ```
293
+
294
+ If you use the CLI without the plugin, no hook injects the guidance block. Add this rule
295
+ to the same block, so that each session reads the guidance itself:
296
+
297
+ ```markdown
298
+ - At the start of each session in a registered project, run
299
+ `sessionmemory inject --cwd .` and follow the guidance it prints.
300
+ ```
301
+
253
302
  ## Documentation
254
303
 
255
304
  | Page | What it covers |
@@ -179,7 +179,8 @@ and the summary is what a search result shows. Both state the fact and not the t
179
179
  ## What a session sees
180
180
 
181
181
  `sessionmemory inject` prints the block a session starts with. This is the block for a
182
- project holding four learnings, one spec, one plan, and two open backlog items:
182
+ project holding four learnings, one spec, one plan, one reference doc, and two open
183
+ backlog items:
183
184
 
184
185
  ```
185
186
  ## Using this vault
@@ -187,7 +188,8 @@ project holding four learnings, one spec, one plan, and two open backlog items:
187
188
  Durable memory for this project lives in a vault of markdown pages. Nothing below is
188
189
  loaded for you: the titles are what the vault holds, and each is one `sessionmemory search`
189
190
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
190
- `specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
191
+ `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
192
+ and Edit.
191
193
  `sessionmemory project --json` prints every path.
192
194
 
193
195
  - Before assuming nothing was written down, search: `sessionmemory search "<words>"`
@@ -214,6 +216,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
214
216
  configuring a service, rotating a credential, or recovering from an outage.
215
217
  Whenever you write one, create it with `sessionmemory new runbook --title "..." --cwd .`,
216
218
  which prints its path, never in another folder or the repository.
219
+ - Reference: `reference/` holds this project's private docs, such as hosting
220
+ settings, where each credential lives, or a data dictionary, kept out of its
221
+ repository. Any it holds are listed below; before working in an area, read the one
222
+ whose name matches. Keep a doc current by editing it in place. Create one with
223
+ `sessionmemory new reference --title "..." --cwd .`, which prints its path. Public
224
+ documentation stays in the repository.
217
225
  - Learnings are captured at session end, not by you mid-session. When the user asks
218
226
  to keep one now: `sessionmemory new learning --title "..." --summary "..." --cwd .`
219
227
  creates the page and prints the path to write prose into. Title and summary state
@@ -226,6 +234,10 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
226
234
  - Stripe retries a webhook for 72 hours, so the handler must be idempotent
227
235
  - The nightly reconciliation job must start after the 02:00 bank feed
228
236
 
237
+ ## Reference docs
238
+
239
+ reference/hosting.md
240
+
229
241
  ## Open work
230
242
 
231
243
  2 open backlog items
@@ -235,6 +247,43 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
235
247
  A page body never enters that block, so its cost grows with the number of pages and not
236
248
  with their length. The titles say what exists. `sessionmemory search` returns what they say.
237
249
 
250
+ ## Add rules to your CLAUDE.md
251
+
252
+ The guidance block above tells a session how to read and write the vault. It does not
253
+ control where other skills and plugins write their files. A planning skill writes its
254
+ plans and specs to the path it chose for itself, often under the repository's `docs/`.
255
+ Rules in a `CLAUDE.md` file send that work to the vault.
256
+
257
+ Put the rules in your user file, `~/.claude/CLAUDE.md`, so that they apply in every
258
+ registered project. A project `CLAUDE.md` is committed with the code. Other contributors
259
+ read it, and they have no access to your vault.
260
+
261
+ Copy this block into the file:
262
+
263
+ ```markdown
264
+ ## Session memory
265
+
266
+ - Write every plan, spec, and design document into the sessionmemory vault, including
267
+ the ones a skill or plugin generates. Create them with
268
+ `sessionmemory new spec --title "..." --cwd .` and
269
+ `sessionmemory new plan --title "..." --cwd .`. Never write them under the
270
+ repository's `docs/`, which holds public documentation.
271
+ - Write every runbook (a step-by-step procedure to follow by hand) with
272
+ `sessionmemory new runbook --title "..." --cwd .`.
273
+ - Keep documentation that describes the code and is safe to publish in the repository.
274
+ Put private documentation about a project, such as hosting settings or where each
275
+ credential lives, in the vault with `sessionmemory new reference --title "..." --cwd .`,
276
+ and edit that file in place afterward.
277
+ ```
278
+
279
+ If you use the CLI without the plugin, no hook injects the guidance block. Add this rule
280
+ to the same block, so that each session reads the guidance itself:
281
+
282
+ ```markdown
283
+ - At the start of each session in a registered project, run
284
+ `sessionmemory inject --cwd .` and follow the guidance it prints.
285
+ ```
286
+
238
287
  ## Documentation
239
288
 
240
289
  | Page | What it covers |
@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.7.0"
14
+ version = "0.8.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -12,7 +12,7 @@
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.7.0"
15
+ version = "0.8.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.cli:main"
@@ -19,7 +19,8 @@ from sessionmemory.lib import backlog, field, paths
19
19
  from sessionmemory.lib.config import now, today
20
20
 
21
21
  app = typer.Typer(
22
- no_args_is_help=True, help="Create a learning, spec, plan, runbook, or backlog item."
22
+ no_args_is_help=True,
23
+ help="Create a learning, spec, plan, runbook, reference doc, or backlog item.",
23
24
  )
24
25
 
25
26
  # Typer lists an Enum's members in --help and rejects anything else at parse time, so the
@@ -131,6 +132,28 @@ def new_runbook(
131
132
  )
132
133
 
133
134
 
135
+ @app.command("reference")
136
+ def new_reference(
137
+ title: str = TITLE,
138
+ body: str = BODY,
139
+ body_file: Path | None = BODY_FILE,
140
+ cwd: Path | None = CWD,
141
+ *,
142
+ as_json: bool = JSON,
143
+ ) -> None:
144
+ """Create a reference doc for this project."""
145
+ body = resolve_body(body, body_file)
146
+ vault = require_vault()
147
+ slug = require_project(vault, cwd)
148
+ try:
149
+ path = field.new_reference(
150
+ paths.reference_dir(vault, slug), title=title, body=body, now=now()
151
+ )
152
+ except field.PageError as error:
153
+ fail(str(error))
154
+ _report(path, as_json=as_json)
155
+
156
+
134
157
  @app.command("backlog", help="Add one open item to this project's backlog.md.")
135
158
  def new_backlog(
136
159
  kind: Kind = KIND,
@@ -46,7 +46,8 @@ One folder per project under `projects/`. Inside each:
46
46
 
47
47
  - `learnings/` is a field: flat markdown pages, embedded and searchable.
48
48
  - `logs/` is a second field, one page per session, searched on request.
49
- - `specs/`, `plans/`, `runbooks/`, and `backlog.md` are plain files, never indexed.
49
+ - `specs/`, `plans/`, `runbooks/`, `reference/`, and `backlog.md` are plain files, never
50
+ indexed.
50
51
  - `backlog.md` is the list of open items for the project, one line each, sized by
51
52
  effort and grouped by commit type.
52
53
 
@@ -157,8 +157,8 @@ def claim_filename(directory: Path, title: str, *, stem: str | None = None) -> P
157
157
  raise PageError(msg)
158
158
 
159
159
 
160
- def _create(directory: Path, meta: dict[str, Any], body: str, *, stem: str | None) -> Path:
161
- path = claim_filename(directory, str(meta["title"]), stem=stem)
160
+ def _fill(path: Path, meta: dict[str, Any], body: str) -> Path:
161
+ """Write a freshly claimed file, releasing the claim if the write does not land."""
162
162
  try:
163
163
  atomic.write_text(path, serialize(meta, body))
164
164
  except BaseException:
@@ -167,6 +167,10 @@ def _create(directory: Path, meta: dict[str, Any], body: str, *, stem: str | Non
167
167
  return path
168
168
 
169
169
 
170
+ def _create(directory: Path, meta: dict[str, Any], body: str, *, stem: str | None) -> Path:
171
+ return _fill(claim_filename(directory, str(meta["title"]), stem=stem), meta, body)
172
+
173
+
170
174
  def new_page(directory: Path, *, title: str, summary: str, body: str, now: str) -> Path:
171
175
  """Create a memory page with the five fields the spec defines."""
172
176
  meta = {
@@ -193,6 +197,32 @@ def new_document(directory: Path, *, title: str, body: str, now: str, day: str)
193
197
  return _create(directory, meta, body, stem=dated_stem(title, day))
194
198
 
195
199
 
200
+ def new_reference(directory: Path, *, title: str, body: str, now: str) -> Path:
201
+ """Create a reference doc: a titled, undated file kept current by editing in place.
202
+
203
+ The name is the title's slug alone, since a date would claim an age the doc stops
204
+ having at its first edit. A taken name is refused rather than suffixed, because a
205
+ second copy of a living doc splits it into two that drift apart.
206
+
207
+ Raises:
208
+ PageError: If the title yields no slug or the name is taken.
209
+ """
210
+ try:
211
+ stem = slugify(title)
212
+ except ValueError as error:
213
+ raise PageError(str(error)) from error
214
+ path = directory / f"{stem}.md"
215
+ if not atomic.claim(path):
216
+ existing = read_page(path).title
217
+ if existing and existing != title:
218
+ # Two titles can share a slug once it is cut to the id limit.
219
+ msg = f"{path.name} in {directory} already holds {existing!r}; choose another title"
220
+ else:
221
+ msg = f"{path.name} already exists in {directory}; edit it instead"
222
+ raise PageError(msg)
223
+ return _fill(path, {"title": title, "created": now, "updated": now}, body)
224
+
225
+
196
226
  def dated_stem(title: str, day: str) -> str:
197
227
  """Return `<day>-<slug>`, with the slug shortened so the whole stem fits the id limit.
198
228
 
@@ -26,6 +26,7 @@ class Injection:
26
26
  titles: tuple[str, ...]
27
27
  open_backlog: int
28
28
  specs: int
29
+ reference: tuple[str, ...]
29
30
 
30
31
 
31
32
  def _sort_key(title: str) -> str:
@@ -48,18 +49,39 @@ def _spec_count(directory: Path) -> int:
48
49
  return sum(1 for _ in field.iter_pages(directory))
49
50
 
50
51
 
52
+ def _reference_docs(directory: Path) -> tuple[str, ...]:
53
+ """List every markdown file, conformant name or not, since a doc moved in by hand keeps its name."""
54
+ if not directory.is_dir():
55
+ return ()
56
+ return tuple(
57
+ sorted(
58
+ path.name
59
+ for path in directory.iterdir()
60
+ if path.is_file()
61
+ and path.suffix.lower() == ".md"
62
+ # A dotfile is hidden metadata, such as a macOS `._` resource fork, not a doc.
63
+ and not path.name.startswith(".")
64
+ and not field.is_debris(path.name)
65
+ )
66
+ )
67
+
68
+
51
69
  def build(vault: Path, slug: str) -> Injection:
52
70
  """Read the project's pages and files; the index is never consulted here.
53
71
 
54
72
  Specs are counted rather than listed. A spec outlives the work it describes, so a
55
73
  list of them is a changelog rather than open work, and it grows without bound. The
56
74
  count says whether listing `specs/` is worth a call, which is all a session needs.
75
+
76
+ Reference docs are listed by filename. They are few and edited in place rather than
77
+ accumulated, and a name a session recognizes is what sends it to read one.
57
78
  """
58
79
  return Injection(
59
80
  project=slug,
60
81
  titles=_titles(paths.learnings_dir(vault, slug)),
61
82
  open_backlog=_open_backlog(paths.backlog_path(vault, slug)),
62
83
  specs=_spec_count(paths.specs_dir(vault, slug)),
84
+ reference=_reference_docs(paths.reference_dir(vault, slug)),
63
85
  )
64
86
 
65
87
 
@@ -68,7 +90,8 @@ GUIDANCE = """## Using this vault
68
90
  Durable memory for this project lives in a vault of markdown pages. Nothing below is
69
91
  loaded for you: the titles are what the vault holds, and each is one `{command} search`
70
92
  away. The project's folder has `learnings/` and `logs/`, searched by meaning, beside
71
- `specs/`, `runbooks/`, and `backlog.md`, which are ordinary files you Read and Edit.
93
+ `specs/`, `runbooks/`, `reference/`, and `backlog.md`, which are ordinary files you Read
94
+ and Edit.
72
95
  `{command} project --json` prints every path.
73
96
 
74
97
  - Before assuming nothing was written down, search: `{command} search "<words>"`
@@ -95,6 +118,12 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
95
118
  configuring a service, rotating a credential, or recovering from an outage.
96
119
  Whenever you write one, create it with `{command} new runbook --title "..." --cwd .`,
97
120
  which prints its path, never in another folder or the repository.
121
+ - Reference: `reference/` holds this project's private docs, such as hosting
122
+ settings, where each credential lives, or a data dictionary, kept out of its
123
+ repository. Any it holds are listed below; before working in an area, read the one
124
+ whose name matches. Keep a doc current by editing it in place. Create one with
125
+ `{command} new reference --title "..." --cwd .`, which prints its path. Public
126
+ documentation stays in the repository.
98
127
  - Learnings are captured at session end, not by you mid-session. When the user asks
99
128
  to keep one now: `{command} new learning --title "..." --summary "..." --cwd .`
100
129
  creates the page and prints the path to write prose into. Title and summary state
@@ -107,6 +136,9 @@ def render(injection: Injection, *, command: str = "sessionmemory") -> str:
107
136
  lines.extend(f" - {title}" for title in injection.titles)
108
137
  if not injection.titles:
109
138
  lines.append(" nothing yet")
139
+ if injection.reference:
140
+ lines.extend(["", "## Reference docs", ""])
141
+ lines.extend(f" reference/{name}" for name in injection.reference)
110
142
  lines.extend(["", "## Open work", ""])
111
143
  item = "item" if injection.open_backlog == 1 else "items"
112
144
  lines.append(f" {injection.open_backlog} open backlog {item}")
@@ -123,4 +155,5 @@ def payload(injection: Injection, *, command: str) -> dict[str, object]:
123
155
  "titles": list(injection.titles),
124
156
  "open_backlog": injection.open_backlog,
125
157
  "specs": injection.specs,
158
+ "reference": list(injection.reference),
126
159
  }
@@ -1,9 +1,9 @@
1
1
  """Where a project's files live inside the vault.
2
2
 
3
3
  `learnings/` and `logs/` are fields: flat directories of pages, each with its own
4
- index. `specs/`, `plans/`, `runbooks/`, and `backlog.md` sit beside them and are never
5
- indexed. A
6
- project's files are found by its slug and nothing else; there is no global scope.
4
+ index. `specs/`, `plans/`, `runbooks/`, `reference/`, and `backlog.md` sit beside them
5
+ and are never indexed. A project's files are found by its slug and nothing else; there
6
+ is no global scope.
7
7
  """
8
8
 
9
9
  from __future__ import annotations
@@ -21,6 +21,7 @@ LOGS_DIR = "logs"
21
21
  SPECS_DIR = "specs"
22
22
  PLANS_DIR = "plans"
23
23
  RUNBOOKS_DIR = "runbooks"
24
+ REFERENCE_DIR = "reference"
24
25
  BACKLOG_FILE = "backlog.md"
25
26
 
26
27
  FIELD_DIRS: tuple[str, ...] = (LEARNINGS_DIR, LOGS_DIR)
@@ -56,6 +57,11 @@ def runbooks_dir(vault: Path, slug: str) -> Path:
56
57
  return project_dir(vault, slug) / RUNBOOKS_DIR
57
58
 
58
59
 
60
+ def reference_dir(vault: Path, slug: str) -> Path:
61
+ """Return the project's reference folder."""
62
+ return project_dir(vault, slug) / REFERENCE_DIR
63
+
64
+
59
65
  def backlog_path(vault: Path, slug: str) -> Path:
60
66
  """Return the project's backlog checklist file."""
61
67
  return project_dir(vault, slug) / BACKLOG_FILE
@@ -73,6 +79,7 @@ def project_paths(vault: Path, slug: str) -> dict[str, str]:
73
79
  "specs": str(specs_dir(vault, slug)),
74
80
  "plans": str(plans_dir(vault, slug)),
75
81
  "runbooks": str(runbooks_dir(vault, slug)),
82
+ "reference": str(reference_dir(vault, slug)),
76
83
  "backlog": str(backlog_path(vault, slug)),
77
84
  }
78
85