Product Docs

Product Docs

Living, user-facing product documentation per project — kept current by the agent, stored in your vault. Lebende, User-facing Produkt-Dokumentation pro Projekt — vom Agent aktuell gehalten, gespeichert in deinem Vault.

---

🇬🇧 English

What it is

Beyond memories (lessons, decisions, project facts), the vault can hold product documentation: docs written for the end user of whatever you're building — "what does this feature do, how do I use it, what are the quirks". They live as plain markdown in your vault:

<vault>/
  memories/            ← lessons, decisions, project-facts, …
  documents/           ← PDFs, scans, contracts (sidecars)
  dokumentationen/     ← product docs, one folder per project
    bastra/
      doku-bastra-user-guide.md
    carnexus/
      doku-carnexus-ocr-import.md

One markdown file per feature area, with a stable id (doku-<project>-<area>). The agent updates a doc in place — the file is a living document, not an append-only trail.

This is deliberately distinct from developer documentation: file maps, architecture and "what was built where" stay in project-fact memories (see the skill's project-topology section). Product docs carry no code internals and no file paths.

Enabling it

Off by default. Two settings, via CLI:

bastra config set docs.mode suggest    # agent PROPOSES a doc update when a feature area is finished
bastra config set docs.mode auto       # agent updates the doc autonomously (one-line ack)
bastra config set docs.mode off        # default — no instruction is injected at all
bastra config set docs.language de     # language the docs are written in (default: en)

The same settings are exposed for local UIs (e.g. the Bastra Mac app's options pane) via the loopback-only REST endpoint:

GET  /settings/docs            → { "mode": "suggest", "language": "de" }
POST /settings/docs            body: { "mode": "auto" } and/or { "language": "en" }

The current mode is also visible in the bastra status panel.

How capture works

With docs.mode set to suggest or auto, the SessionStart hook injects a <bastra-product-docs> block into every session (when a project is detected). It instructs the agent:

• Trigger: only when a user-facing feature area is completely finished — works end-to-end, the user confirmed, or the commit landed. Never for work in progress, refactors, or internal-only changes.
• Update-in-place: read the existing doc first (find_document → read_document), merge, send the complete updated markdown via save_product_doc.
• Audience: the end user. Features, usage, tips, quirks — in the configured docs.language.
• Mode: suggest proposes the update first (one line) and writes only after you agree; auto writes autonomously and acks in one line.

The opt-in Stop hook complements this: its feature-completion suggestion (user-confirmed git commit + several source files) reminds the agent to also refresh the affected product doc.

Ranking

Product docs share type: doc with document sidecars. In the default recall they are damped ×0.5 — docs never age, and long doc bodies would otherwise crowd lessons out of the top-k. find_document (and any recall with type: "doc") ranks them undamped — that's the dedicated lane.

The tool

save_product_doc (MCP + POST /api/v1/save_product_doc) — see Tools Reference for parameters.

---

🇩🇪 Deutsch

Was es ist

Neben Memories (Lessons, Decisions, Project-Facts) kann der Vault Produkt-Dokumentation führen: Doku, geschrieben für den Endnutzer dessen, was du baust — „was tut das Feature, wie benutze ich es, welche Eigenheiten gibt es". Sie liegt als reines Markdown im Vault:

<vault>/
  memories/            ← Lessons, Decisions, Project-Facts, …
  documents/           ← PDFs, Scans, Verträge (Sidecars)
  dokumentationen/     ← Produkt-Doku, ein Ordner pro Projekt
    bastra/
      doku-bastra-user-guide.md
    carnexus/
      doku-carnexus-ocr-import.md

Eine Markdown-Datei pro Feature-Bereich, mit stabiler id (doku-<projekt>-<bereich>). Der Agent aktualisiert die Doku in place — die Datei ist ein lebendes Dokument, kein Append-only-Verlauf.

Bewusst getrennt von Entwickler-Doku: File-Maps, Architektur und „was wurde wo gebaut" bleiben in project-fact-Memories (siehe Projekt-Topologie im Skill). Produkt-Doku enthält keine Code-Interna und keine Dateipfade.

Einschalten

Standardmäßig aus. Zwei Settings, per CLI:

bastra config set docs.mode suggest    # Agent SCHLÄGT das Doku-Update vor, wenn ein Bereich fertig ist
bastra config set docs.mode auto       # Agent aktualisiert die Doku selbstständig (Einzeilen-Ack)
bastra config set docs.mode off        # Default — es wird gar keine Anweisung injiziert
bastra config set docs.language de     # Sprache der Doku (Default: en)

Dieselben Settings sind für lokale UIs (z.B. die Options-Pane der Bastra Mac-App) über den loopback-only REST-Endpoint erreichbar:

GET  /settings/docs            → { "mode": "suggest", "language": "de" }
POST /settings/docs            Body: { "mode": "auto" } und/oder { "language": "en" }

Der aktuelle Modus ist auch im bastra-Status-Panel sichtbar.

Wie die Erfassung funktioniert

Mit docs.mode auf suggest oder auto injiziert der SessionStart-Hook einen <bastra-product-docs>-Block in jede Session (wenn ein Projekt erkannt wurde). Er weist den Agent an:

• Trigger: nur wenn ein User-facing Feature-Bereich komplett fertig ist — läuft end-to-end, User hat bestätigt oder der Commit ist gelandet. Nie bei Work-in-Progress, Refactors oder rein internen Änderungen.
• Update-in-place: erst die bestehende Doku lesen (find_document → read_document), mergen, das komplette aktualisierte Markdown via save_product_doc senden.
• Zielgruppe: der Endnutzer. Features, Bedienung, Tipps, Eigenheiten — in der konfigurierten docs.language.
• Modus: suggest schlägt das Update erst vor (eine Zeile) und schreibt erst nach Zustimmung; auto schreibt selbstständig und ackt einzeilig.

Der Opt-in-Stop-Hook ergänzt das: Seine Feature-Completion-Suggestion (User-bestätigter git commit + mehrere Source-Files) erinnert den Agent daran, auch die betroffene Produkt-Doku aufzufrischen.

Ranking

Produkt-Doku teilt type: doc mit den Document-Sidecars. Im Default-recall wird sie ×0.5 gedämpft — Docs altern nie, und lange Doku-Bodies würden sonst Lessons aus den Top-k drängen. find_document (und jeder recall mit type: "doc") rankt ungedämpft — das ist die dedizierte Lane.

Das Tool

save_product_doc (MCP + POST /api/v1/save_product_doc) — Parameter siehe Tools Reference.