@lovelaces-io/storyteller 0.3.0 → 0.4.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 Storyteller (`@lovelaces-io/storyteller`) is a lightweight TypeScript logging library with zero production dependencies. You report beats of work as they happen; it keeps them and emits them as one structured record when the work finishes. Records go to pluggable audiences.
 
-Version: 0.3.0 (pre-1.0, API may change). Dual output: ESM + CJS.
+Version: 0.3.1 (pre-1.0, API may change). Dual output: ESM + CJS.
 
 ## Narrate your work
 
@@ -84,6 +84,10 @@ Values dropped for size are replaced with an explicit `{ "@truncated": { kind, o
 
 The normalizer never throws. A hostile object cannot break the pipeline.
 
+## Secrets
+
+Redaction happens at capture and again at the storage boundary: values under secret-named keys (`password`, `apiKey`, `dbPassword`, `x-api-key`), and recognisable secret formats inside any string (Stripe/OpenAI/GitHub keys, JWTs, PEM blocks, `Bearer …`, passwords in URLs, `?token=`), become `[redacted]` — error messages and stacks included. It is defense in depth, not a guarantee: a secret that looks like a word passes. Do not report a secret and rely on redaction; do not turn `redact` off in code that persists. `auditRedaction(value)` shows what would be removed, so check a real corpus before trusting coverage. `redactValues: "strict"` trades some legitimate content for more coverage.
+
 ## Output a program can read
 
 For machine consumption, use NDJSON — one JSON object per line, nothing else on the channel:
@@ -185,9 +189,42 @@ Built in: `consoleAudience()` (notes and stories, registered by default), `dbAud
 
 When an audience throws, the failure is reported through `onAudienceError` rather than swallowed, and never propagates into your code. When an audience is too slow, emissions past `maxInFlight` are dropped and counted in `droppedEmissions` on the closing story — so the loss shows up in the record instead of vanishing.
 
+## Keeping stories, and reading them back
+
+A story is the unit of retrieval: complete, ordered, small enough for a context window. A `StoryStore` keeps them and answers structured questions; `storeAudience` is the one-line bridge from delivery.
+
+```typescript
+import { memoryStore, stories, storeAudience } from "@lovelaces-io/storyteller";
+import { fileStore } from "@lovelaces-io/storyteller/store/file";   // Node only
+
+const kept = fileStore("./stories.jsonl");         // or memoryStore() for a browser, a test, one run
+story.audience.add(storeAudience(kept));
+
+await stories(kept).about("checkout").failing().since("24h");   // reads like the question
+await stories(kept).slowerThan("5s").since("7d").oldest().limit(10);
+await stories(kept).under(storyId);                                // its chapters
+await kept.prune(new Date(Date.now() - 30 * 86_400_000));
+```
+
+`stories(store)` is the vocabulary: `about`, `from`, `level`, `atLeast`, `failing`, `succeeding`, `slowerThan`, `since`, `until`, `under`, `newest`, `oldest`, `limit`, `skip`; then `all()`, `first()` or `count()`, or just `await` it. It compiles to a `StoryQuery` object, never a string. `about` searches title, note text, scalar context and error messages; `from` searches the origin. To write an adapter for a database, store `canonicalRow(story)` and make its query agree with `matchesQuery` — that agreement is the contract.
+
+## Rendering stories for humans
+
+Stories are JSON so programs can read them. When a person needs to read one — an admin log screen, a terminal, a chat transcript — use `@lovelaces-io/storyteller-view`, a separate zero-dependency package from the same repo:
+
+```ts
+import { renderStory, renderStoryText } from "@lovelaces-io/storyteller-view";
+
+renderStory(event);            // HTMLElement: timeline of notes, context trees, error with cause chain
+renderStoryText(event, { colors: true }); // string: the same layout as indented text
+```
+
+Both accept a `StoryEvent`, a `NoteEmission`, or a stored record read back from a database or NDJSON. Every marker the normalizer leaves (`@type`, `@truncated`, `[Circular → path]`, `[redacted]`) is shown as what it means rather than as a string, and the DOM renderer inserts text nodes only — never `innerHTML` — because story content is user input. Do not hand-roll a story renderer in an app; reach for the view and theme it with the `--stv-*` custom properties.
+
 ## Architecture
 
 ```
+packages/core/
 src/
   storyteller.ts       — core class, types, event building, delivery
   normalize.ts         — turns any value into something storable
@@ -207,6 +244,10 @@ snippets/
   agents-section.md    — the guidance block consumers paste into their AGENTS.md
 ```
 
+The repository is a workspace: this package is `packages/core`; add-on packages with
+real dependencies (a SQLite store, an MCP server) live beside it under `packages/`
+and are never imported by core.
+
 `snippets/agents-section.md` is the single source for that block. It is embedded
 verbatim in README.md and written by `storyteller init`, and `npm run check:snippet`
 fails the build if the copies drift or it outgrows its 40-line budget. Edit the

package/README.md

@@ -248,6 +248,33 @@ story.audience.add({
 
 When an audience throws, the failure is reported rather than swallowed, and never reaches your code. When one is too slow, emissions past `maxInFlight` are dropped and counted in `droppedEmissions` on the closing record — visible loss beats silent loss.
 
+## Keep Them, Ask Them
+
+A story is the unit of retrieval: complete, ordered, small enough for a context window. Keep them in a store and the question *why did last night's sync fail?* has somewhere to look.
+
+```ts
+import { stories, storeAudience } from "@lovelaces-io/storyteller";
+import { fileStore } from "@lovelaces-io/storyteller/store/file";
+
+const kept = fileStore("./stories.jsonl");   // or memoryStore() anywhere
+story.audience.add(storeAudience(kept));
+
+await stories(kept).failing().since("1h");
+await stories(kept).about("checkout").from("payment-service").level("oops").since("24h");
+await stories(kept).slowerThan("5s").since("7d").oldest().limit(10);
+```
+
+Ask in words; every store answers the same question. Then let an agent ask: **the Librarian** is a read-only MCP server over any store.
+
+```jsonc
+// .mcp.json
+{ "mcpServers": { "storyteller": { "command": "npx", "args": ["-y", "@lovelaces-io/storyteller-mcp", "./stories.jsonl"] } } }
+```
+
+Redaction runs at capture and again at the storage boundary — secret-named keys and recognisable secret formats inside any string — so what is kept is what is safe to keep. Defense in depth, not a guarantee; [SECURITY.md](./SECURITY.md) says exactly what it does not promise.
+
+For a person, `@lovelaces-io/storyteller-view` renders a story as a timeline, in a page or a terminal: [storyteller.lovelaces.io/docs/view](https://storyteller.lovelaces.io/docs/view).
+
 ## Configuration
 
 Every option can also come from the environment, so you can change behavior without touching code:
@@ -300,6 +327,9 @@ const story = useStoryteller({ origin: { who: "worker" } });
 - [How It Works](docs/HOW-IT-WORKS.md) — narrative guide
 - [Changelog](CHANGELOG.md)
 - [For AI Agents](AGENTS.md) — guidance for AI coding assistants
+- [The Library](https://storyteller.lovelaces.io/docs/library) — keep stories, ask in words, let an agent read them back
+- [Story view](https://storyteller.lovelaces.io/docs/view) — `@lovelaces-io/storyteller-view`, stories rendered for humans
+- [The Librarian](packages/mcp/README.md) — `@lovelaces-io/storyteller-mcp`, the read-only MCP server
 
 ## License