beakr-cli 0.3.2__tar.gz → 0.4.0__tar.gz

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/commands/kb-audit.md

@@ -33,4 +33,4 @@ If no specific focus is given, run a general health check. Pass a project's name
    - **Minor** -- style inconsistencies, missing Related Pages sections
    - **Recommendations** -- specific pages to create, merge, or reorganize
 
-Offer to stage fixes with `knowledge_base_write` (actions `edit_section`, `merge` for duplicates, `mv`, `new`) if the user approves. Never call `accept_proposal` unless the user explicitly asks.
+Offer to stage fixes with `knowledge_base_write` (actions `edit_section`, `merge` for duplicates, `mv`, `new`) if the user approves. A `merge` moves only the duplicate sections its `merge_sections` names; the rest are archived with the duplicate. After an `mv`, links elsewhere keep resolving but still show the old title until a `find_replace` updates them. Never call `accept_proposal` unless the user explicitly asks.

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/commands/kb-write.md

@@ -12,8 +12,8 @@ Follow this procedure:
 
 5. **Write the content** following these conventions:
    - The page is `sections`: an ordered list of `{"title": ..., "body": ...}` objects. Beakr writes the `<!-- sec:ID -->` markers and IDs; do not author markers or pass `content`.
-   - Put an inline citation token `{{key}}` immediately after every factual claim, table value, date, title, and relationship.
-   - Give each token a record in that section's `citations`: `{"key": ..., "source_ref": ..., "stance": ...}` using the `source_ref` from a `knowledge_base` read for sources Beakr already has. For this conversation or a note, use a stable key with `source_type` `conversation`, `agent_note`, or `user_note`, plus `source_title` and `meta.excerpt`.
+   - Cite every factual claim, table value, date, title, and relationship right after it. For a source Beakr already has, write the readable reference a `knowledge_base` read printed, in parentheses (`(memo.pdf › p. 7)`); Beakr stores it as that citation. To set its stance, also list it in `citations` as `{"reference": ..., "stance": ...}` or with the read's `source_ref`.
+   - For this conversation or a note, put `{{conversation:<label>}}` after the claim and give it a record in that section's `citations` with the same `key`, `source_type` `conversation` (or `agent_note`, `user_note`), `source_title`, and `meta.excerpt`.
    - Set `stance` to `support`, `qualifies`, or `contradicts`.
    - Add `event_start`, `event_end`, and `date_precision` (day, month, quarter, year, approx) to dated decisions, meetings, milestones, launches, incidents, and other timeline-worthy sections.
    - Use `[[Page Title]]` for cross-references (check targets exist) and `[[Display Text|Page Title]]` when the text differs.
@@ -24,7 +24,8 @@ Follow this procedure:
 6. **Stage the proposal** with `knowledge_base_write`:
    - New page: action `new` with `title`, `page_type`, `summary` (one line on what the page is about), `parent`, `sections`, and `rationale`.
    - Existing page: action `edit_section` with `page`, `section_id`, `new_section_body`, `citations`, `edit_note`, and `rationale`. Read the page first; the new body replaces the whole section.
+   - An `edit_section` write prints the proposal's id and `content_hash`.
 
-7. **Review.** Show the result with `show_proposal`. Call `accept_proposal` only when the user explicitly asks to apply it.
+7. **Review.** Show the result with `show_proposal`, which also names who filed it. Call `accept_proposal` only when the user explicitly asks to apply it, with the `content_hash` the user reviewed as `reviewed_hash`.
 
 Do NOT create stub pages. Every page should have substantive content.

beakr_cli-0.4.0/.claude/skills/beakr/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: beakr
+description: "Access your organization's knowledge base, research questions with citations, and manage knowledge base pages using Beakr's MCP tools. Use when the user asks about their organization, team, projects, people, decisions, or processes -- or wants to create/update knowledge base content."
+---
+
+# Beakr Knowledge Base
+
+Beakr is the team's organizational memory. Teams write decisions, processes, ownership, and dated events here so that 6 months later the answer to "why did we do X" is one search away instead of lost in Slack archives or tribal knowledge.
+
+Use the Beakr MCP tools to search and read existing knowledge — and to add to it when the conversation produces something durable.
+
+## When to use
+
+- User asks about their organization, team, people, decisions, or processes
+- User wants to look something up ("What do we know about X?", "Who owns Y?")
+- User wants to research a topic across documents and connected services
+- User wants to create, update, or audit knowledge base pages
+- **The conversation itself surfaces durable information worth capturing** (see "Proactive capture" below)
+
+## Proactive capture
+
+You are not just a read interface. When the conversation produces something durable, **propose adding it — don't wait to be asked**.
+
+**Capture when all of:**
+- **Durable**: would still matter in 6 months
+- **Shareable**: others would benefit, not just this user right now
+- **Not already in Beakr**: check with `knowledge_base` command `sections` first
+- **In scope**: the user can write to it (their personal project, or a team project they belong to — confirm with `list_projects`)
+
+**Good candidates:**
+- Decisions with rationale ("we chose X over Y because…")
+- Named processes ("here's how we onboard a customer")
+- Role / ownership assignments ("Alex owns billing")
+- Dated events: launches, hires, fundraising rounds, incidents
+- External relationships: investors, partners, key vendors
+- Recurring questions you just answered
+
+**Skip:**
+- Debugging traces, transient state
+- Information already in source code, git history, Linear/Jira tickets
+- Hot takes, speculation, "thinking out loud"
+- Anything the user clearly considers ephemeral
+
+**Etiquette:**
+- **Surface the suggestion before writing**: "This decision about X seems worth capturing — want me to propose it for your wiki?"
+- Never auto-write. Always propose, always wait for explicit OK -- unless the write result says the user's auto-approve is on; then it is applied automatically, so do not ask them to approve it.
+- One capture offer per significant thread — don't pepper the user.
+- Cite the current session as a `conversation` source with `meta.excerpt` so it is traceable.
+
+## Tools
+
+| Tool | When to use |
+|------|-------------|
+| `knowledge_base` | Every read over the wiki, chosen by `command`: `sections`, `grep`, `ls`, `cat`, `hover`, `links`, `references`, `timeline`, `rows` (every map card's Facts, Connections or Findings as one table), `provenance`, `blame`, `sources`, `log`, `diff`, `show`, `ontology`, `suggest_parent`, `diagnostics`, `completions`, `proposals`. |
+| `knowledge_base_write` | Every change, chosen by `action`: `edit_section`, `add_fact`, `add_connection`, `add_finding`, `edit_rows`, `sort_table`, `new`, `edit`, `find_replace`, `mv`, `archive`, `merge`, `copy`, `page_type`. Stages a proposal, with two exceptions that apply at once: `sort_table` only reorders a table, and a project or org `page_type` the verifier accepts is active at once; a global one is refused. On a project-map card use the three `add_*` actions to add one row or one dated finding, and `edit_rows` to change, merge or delete rows (Facts, Connections or Findings). A card's table rows change only through these actions: an `edit_section` or `edit` that would change one is refused, and `find_replace` changes the text around the rows and reports the row matches it left for `edit_rows`. A write to one section or row prints its proposal's id and `content_hash`. |
+| `documents` | Where available: `grep` and `read` over the original documents themselves, for exact wording a page does not carry. |
+| `read_file` | The original document a citation points at. Pass the citation's readable reference (`memo.pdf › p. 7`), the `path › place` from a Sources line (`deals/acme/memo.pdf › p. 7`), or the file id. It reads files and canvases only: for a connected item (Slack, email, calendar, Jira) use its excerpt and open its url. Long files come back in pieces (`offset`). |
+| `research` | When your client exposes it: one cited answer across the knowledge base, documents and connected services (Slack, Gmail, Calendar, Jira...). |
+| `integrations` | Live reads of the user's connected services (Slack, Drive, Gmail, Jira, Notion, Benchling...), as the user, with the read-only tools Beakr's own agent uses: `command: list` names the tools you can call and their options, `describe` with `tool` gives one tool's schema, and `call` with `tool` runs it with its options in `arguments` (`connector_id` when a service is connected twice). A call ends with a Sources list whose `source_ref` a Knowledge write accepts as a citation. For what the organization already knows, the knowledge base comes first. |
+| `show_proposal` / `accept_proposal` / `dismiss_proposal` | Review a staged proposal, which names who filed it ("filed by Dana Reyes via claude-code/2.1"); accept only when the user explicitly asks, passing the `content_hash` the write or `show_proposal` printed as `reviewed_hash`. A proposal that changed since it was shown is refused; one that changes a card's table rows is not accepted without the hash. Where the organization or project requires a person to accept what agents write, `accept_proposal` is refused (`person_review_required`) and nothing is applied; the hosted server's `show_proposal` says "Needs a person to accept". Tell the user it waits for them to accept in Beakr, and do not retry. |
+| `list_projects` | Discover projects (including the personal one) to use as `scope`. |
+| `get_profile`, `wiki_stats`, `wiki_graph` | Org/project profile, counts, and the most-connected pages. |
+| `context` | The user's Beakr context for a project (its name or ID): profile, recent activity, relevant memories and skills. |
+| `conversations_search` / `import_conversation` | Find past agent sessions and chats that answered something; import a session transcript. |
+| `beakr_version` / `update_beakr` | Check for a newer Beakr release; update only when the user asks. |
+
+Every tool is listed from the start; call it directly. Only a server started with `BEAKR_MCP_TOOLS=eager` lists a smaller set plus `discover_tools`, which adds the tools it finds. A tool missing on a self-hosted installation is one that installation does not provide.
+
+Both `knowledge_base` tools take a `command`/`action`, a flat `arguments` object, and an optional `scope`:
+
+```
+knowledge_base(command="sections", arguments={"query": "who owns billing"})
+knowledge_base(command="cat", arguments={"page": "Billing", "section_id": "sec_owner"})
+knowledge_base_write(action="edit_section", scope="Team Wiki", arguments={...})
+```
+
+There is no `search` command. Use `sections` (semantic, start here) or `grep` (literal text).
+
+## Reading evidence
+
+- **Start with `sections`.** Each hit shows the document passage (a verbatim excerpt) that supports it. Quote it directly; open the file only when the value you need is not in the excerpt.
+- **Four ways to read, combined as the task needs.**
+
+  | Mode | Commands | Use it for | It cannot |
+  | --- | --- | --- | --- |
+  | File system | `ls`, `cat`, `grep`; `documents` grep and read for originals | browsing, reading a page, exact names and ids, the original document | rank or count by a fact's value |
+  | Graph | `links`, `hover`, `references`, `timeline` | a record's parties, instruments and documents, a chain, the order of events | "every" across records it does not reach |
+  | Database | `rows` (`beakr kb rows`); `query` (`beakr kb query`, where enabled: one SQL `SELECT`, or a JSON spec) for what rows cannot express | every, how many, latest, largest, compare, as-of, what connects to X; multi-step joins, custom aggregates, X and not Y | see what was never structured into a card's tables: confirm a count with `ls` or `grep` |
+  | Meaning | `sections`; `query` with `semantic` (`rank_fields_by`) for field names | something you can describe but cannot name | count or enumerate: it ranks and stops |
+
+  Find by meaning or in the database, walk the graph, confirm in the original. Do not extract the documents and grep them; every document, its date and matter are already indexed.
+- **`rows` as a database.** Every row carries its entity (the card's title), entity_type (page type), the table, the field (attribute or relation), the value (or `to`), When and its sources. Filter (`table`, `page_type`, `entity` (one title, or several as a list, `a|b|c` or `^(a|b)$`; the reply names any title that matched no card), `to` for every connection involving a page, `connected_to` for cards linked to a page either way, `attribute`, `query`, `regex: true` for patterns, dates, `current_only`, `as_of` for each card's value on a date), sort (`order_by` any column, or `amount` and `date` for typed values; `descending`) and aggregate (`group_by` entity, entity_type, year or a column: counts, sums, min, max; `group_by: value` groups a category field's consolidated values and any other value by its text). `match` sets how `attribute` finds a field: `exact` (the name or an alias), `similar` (also names holding its words) or `meaning` (the default: also the closest name by meaning, where the rows index is on); the reply says which field it used. `view: fields` lists the field names cards actually use, and `field_id` picks one.
+- **0 rows is not absence.** It means no scanned card states the fact under that name. Retry with the names the reply suggests or `view: fields`, then `sections` and the cited documents; never conclude a fact does not exist from an empty `rows`.
+- **Results stay under about 6k tokens.** When `next` appears, page with it rather than re-querying.
+- **Exact wording:** `sources {page}` lists every cited passage; `read_file` with a citation's reference, a file id or a path opens the original.
+
+## Find, then verify in the file
+
+1. **Find** with the knowledge base (`sections`, `rows`, `cat`). Each citation reads as the document and the place in it, in parentheses, naming the file by its drive path when it is known: `Base rent is $48,000 per year (deals/acme/memo.pdf › p. 7).` A cited message, email, event or comment is dated by its own time, and its url opens that item when the connector gives one. Each Sources line names where a cited document lives, every place cited in it, its `read_file` id and its `source_ref`: `- deals/acme/memo.pdf › p. 7, p. 9 · read_file <id> · source_ref <ref>`.
+2. **Follow** that `path › place` with `read_file` (`deals/acme/memo.pdf › p. 7`, `book.xlsx › sheet 2, B4:D9`); it returns the text around that place. When the files are on your local disk, open the path there directly. Where the `documents` tool is available, its `read` of a path in the wrong subfolder opens the one file of that name in the same record folder and says which path it opened, and a spreadsheet read ends with the first 50 rows of each sheet.
+3. **Verify** every decisive value (an amount, date, count, name) in the file before you rely on it. When the file and a card disagree, the file wins: say so, and cite the file by its reference.
+- **Codex:** print only the result's text, and make one Knowledge call per exec cell.
+
+## Quick decision tree
+
+```
+User asks a question about their org, a fact, a decision or a page
+  → knowledge_base sections {query}; quote the excerpt, or cat {page, section_id} on the best hit
+
+User asks a broad question and research is available
+  → research(query=...)
+
+User asks for the most recent or largest X
+  → knowledge_base rows {table: facts, page_type, attribute, order_by: when (or value), descending: true}; cat the top few, then their children for the executed documents
+
+User asks for every X involving a party, client or instrument
+  → knowledge_base rows {table: connections, to: <page>} or links {page, page_type, relation}
+
+User asks how many X, or for counts per group
+  → knowledge_base ls {page_type} (the whole population, paged), then check each; rows {..., group_by} for counts and totals per group
+
+User asks everything about one record
+  → knowledge_base hover {page}, ls {parent: <page>}, links {page, direction: out}, timeline {page}
+
+User needs the exact wording or a value the excerpt lacks
+  → read_file {path: "<path> › <place>"} from the Sources line (or the citation's reference)
+
+User wants an exact name, ID, or phrase
+  → knowledge_base grep {query}
+
+User wants to browse pages
+  → knowledge_base ls {parent?, page_type?, sort_by?}
+
+User wants to know what happened when
+  → knowledge_base timeline {timeline_query?, start_date?, end_date?}
+
+User wants to verify sources for a claim
+  → knowledge_base provenance {page} or blame {page}
+
+User wants to create/update a page
+  → One specific thing (person, organization, product, system, model, study, decision, event) is a card: run ontology first and use the most specific card type, then add_fact / add_connection / add_finding with evidence. Topic, overview and index pages tie cards together and need no card shape. See [reference/writing-pages.md](reference/writing-pages.md)
+
+You established something the organization will want again (after a cited answer)
+  → propose it: add_fact {page, attribute, value, evidence} for a sourced value (reuse the attribute names rows view: fields lists); add_connection {page, relation, to, evidence} on the more specific card; add_finding {page, date, kind, text, evidence} for your conclusion. An out-of-date value gets a newer dated row, not a deletion.
+
+User wants to audit knowledge base quality
+  → See [reference/auditing.md](reference/auditing.md)
+```
+
+## Scoping
+
+- `knowledge_base` and `knowledge_base_write` take `scope`: a project name or ID. Omit it on reads to search everything the user can see.
+- A `scope` that names no project the user can read is refused with the closest names (`scope_not_found`, or `scope_ambiguous` when several share the name); it is never widened to everything. Retry with a name or ID `list_projects` printed.
+- `research`, `documents`, `read_file`, `wiki_stats` and `wiki_graph` take `project`. Pass the project's ID from `list_projects` to work on every server; the local CLI server (`beakr mcp`) also accepts its name and refuses one that names no readable project as `scope` is refused. On `read_file` it opens only a file in that project.
+- The personal project is a project like any other: `list_projects` reports it with type `personal`. Pass its name or ID as the scope.
+
+## Citing sources
+
+Always cite sources when presenting information from the knowledge base:
+- Cite with the readable reference a result prints, in parentheses: `(tax-memo.docx › p. 7)`, `(#deals › message 2026-03-04 14:02 UTC)`, `(ENG-12)`, `(Page Title › Section)`; to people, link it when it has a url
+- In writes, cite with that readable reference as `reference` (or a read's `source_ref`), and only this conversation (`conversation` with `meta.excerpt`), files the user uploaded, a web page (its http(s) URL, title and the quoted passage), or sources Knowledge already cites; anything else is refused `citation_not_citeable`
+- Include the page title so the user can find it
+- `research` answers cite the same way, with a Sources list per document -- keep the references when you present them
+- An excerpt marked `(paraphrase)`, `(human asserted)`, or `(unverified)` is not a checked quote; open the source before relying on it
+- For claims that need verification, use `provenance` to show supporting/contradicting sources
+- When writing pages, see [reference/writing-pages.md](reference/writing-pages.md) for citation records
+
+## Page references
+
+`page` accepts any of:
+- Title (e.g., `"API Design"`)
+- Slug (e.g., `api-design`)
+- UUID
+- Wiki citation key from a read (e.g., `wiki:8f3a0c21`)
+
+## Advanced workflows
+
+- **Deep research**: See [reference/research-workflow.md](reference/research-workflow.md)
+- **Cards or originals**: read cards first; compute from the original files when the answer needs math, exact values or a disputed source. See [reference/research-workflow.md](reference/research-workflow.md#cards-or-the-original-files)
+- **Writing pages**: See [reference/writing-pages.md](reference/writing-pages.md)
+- **Auditing quality**: See [reference/auditing.md](reference/auditing.md)
+- **Understanding provenance**: See [reference/provenance.md](reference/provenance.md)
+
+## Examples
+
+- [examples/answer-org-question.md](examples/answer-org-question.md) -- Answering "Who owns onboarding?"
+- [examples/research-topic.md](examples/research-topic.md) -- Deep research on a topic
+- [examples/write-decision-page.md](examples/write-decision-page.md) -- Creating a decision record

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/skills/beakr/examples/answer-org-question.md

@@ -12,7 +12,7 @@ Call `research` with the question:
 research(query="who owns the onboarding flow")
 ```
 
-The response returns a cited answer mentioning Sarah Chen [1] and the pages it drew on.
+The response returns a cited answer mentioning Sarah Chen (Onboarding › Owner) and the pages it drew on.
 
 ### Step 2: Verify if needed
 If the user wants more detail, find the exact section and read just that:

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/skills/beakr/examples/write-decision-page.md

@@ -23,7 +23,7 @@ Suggested parent: "API Architecture".
 research(query="internal API architecture GraphQL REST", project="<platform project id>")
 knowledge_base(command="sources", arguments={"page": "API Architecture"})
 ```
-Note each source's citation key and `source_ref`.
+Note the readable reference each source is cited by (`api-decision.docx › p. 2`).
 
 ### Step 4: Stage the page
 
@@ -40,18 +40,14 @@ knowledge_base_write(
     "sections": [
       {
         "title": "Summary",
-        "body": "The engineering team decided to migrate the internal API from REST to GraphQL, effective Q2 2026 {{gdrive:api-decision-doc}}. The public API remains REST {{gdrive:api-decision-doc}}.",
-        "citations": [
-          {"key": "gdrive:api-decision-doc", "source_ref": "beakr-source:v1:...", "stance": "support"}
-        ]
+        "body": "The engineering team decided to migrate the internal API from REST to GraphQL, effective Q2 2026 (api-decision.docx › p. 1). The public API remains REST (api-decision.docx › p. 1)."
       },
       {
         "title": "Decision",
-        "body": "**Decision maker:** Sarah Chen (CTO) {{gdrive:api-decision-doc}}\n\nAdopt GraphQL for internal service communication using Apollo Federation {{gdrive:api-decision-doc}}. It reduces over-fetching by 60% based on traffic analysis {{conversation:graphql-traffic}}.",
+        "body": "**Decision maker:** Sarah Chen (CTO) (api-decision.docx › p. 1)\n\nAdopt GraphQL for internal service communication using Apollo Federation (api-decision.docx › p. 2). It reduces over-fetching by 60% based on traffic analysis {{conversation:graphql-traffic}}.",
         "event_start": "2026-03-15",
         "date_precision": "day",
         "citations": [
-          {"key": "gdrive:api-decision-doc", "source_ref": "beakr-source:v1:...", "stance": "support"},
           {
             "key": "conversation:graphql-traffic",
             "source_type": "conversation",
@@ -63,10 +59,7 @@ knowledge_base_write(
       },
       {
         "title": "Alternatives considered",
-        "body": "1. **Keep REST, add OpenAPI codegen** -- lower migration cost but doesn't solve over-fetching {{gdrive:api-decision-doc}}\n2. **gRPC** -- better performance but weaker tooling for our stack {{gdrive:api-decision-doc}}",
-        "citations": [
-          {"key": "gdrive:api-decision-doc", "source_ref": "beakr-source:v1:...", "stance": "support"}
-        ]
+        "body": "1. **Keep REST, add OpenAPI codegen** -- lower migration cost but doesn't solve over-fetching (api-decision.docx › p. 2)\n2. **gRPC** -- better performance but weaker tooling for our stack (api-decision.docx › p. 2)"
       },
       {
         "title": "Related Pages",
@@ -81,11 +74,11 @@ knowledge_base_write(
 ```
 show_proposal(proposal_id="...")
 ```
-Call `accept_proposal` only after the user explicitly says to apply it.
+Call `accept_proposal` only after the user explicitly says to apply it, passing the `content_hash` the write and `show_proposal` printed as `reviewed_hash`. If it is refused with `person_review_required`, the project needs a person to accept it: the user does that in Beakr.
 
 ## Key points
 - Use the `decision` page type; include the date (`event_start` + `date_precision`), decision maker, and alternatives
 - `sections` is a list of `{title, body}`; Beakr adds the section markers
-- Put an inline `{{key}}` token after every factual claim, and a matching citation record in that section
-- Reuse `source_ref` for sources Beakr already has; cite this conversation with `source_type: "conversation"` and `meta.excerpt`
+- Cite every factual claim inline: a source Beakr already has by the readable reference a read printed, in parentheses (Beakr stores it as that citation); this conversation as `{{conversation:<label>}}` with a matching `conversation` record in that section
+- A record in `citations` can also cite a source Beakr has by `reference` or `source_ref`
 - Link related pages with `[[Page Title]]`

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/skills/beakr/reference/auditing.md

@@ -24,7 +24,7 @@ Use `links {page}` or `references {page}` to inspect a specific page's neighborh
 ### 4. Spot structural issues
 
 From `ls` results, look for:
-- Duplicate or near-duplicate page titles (fix with `merge`, not `archive`)
+- Duplicate or near-duplicate page titles (fix with `merge` and its `merge_sections`, not `archive`)
 - Deeply nested hierarchies (more than 3 levels is usually too deep)
 - Pages without a parent (use `suggest_parent {page}` to find a home)
 - Pages that look like stubs
@@ -51,4 +51,4 @@ Organize by severity:
 - **Minor** -- style inconsistencies, missing Related Pages sections
 - **Recommendations** -- specific pages to create, merge, or reorganize
 
-Offer to stage fixes with `knowledge_base_write` (`edit_section`, `merge`, `mv`, `new`) if the user approves.
+Offer to stage fixes with `knowledge_base_write` (`edit_section`, `merge`, `mv`, `new`) if the user approves. See [writing-pages.md](writing-pages.md#renaming-merging-and-replacing-text) for what `merge` carries and what `mv` leaves.

{beakr_cli-0.3.2 → beakr_cli-0.4.0}/.claude/skills/beakr/reference/provenance.md

@@ -12,7 +12,7 @@ knowledge_base(command="blame", arguments={"page": "API Design"})
 ```
 
 ### sources
-The source documents behind a page, each with the other pages that draw on it. Also accepts a source title or citation token as `page` to get that one document's entry.
+The source documents behind a page, each with the other pages that draw on it. Also accepts a source title (a cited file's name) as `page` to get that one document's entry.
 
 ```
 knowledge_base(command="sources", arguments={"page": "API Design"})

beakr_cli-0.4.0/.claude/skills/beakr/reference/research-workflow.md

@@ -0,0 +1,64 @@
+# Deep Research Workflow
+
+Use this workflow when the user needs a thorough, multi-source analysis of a topic.
+
+## Procedure
+
+### 1. Discover the landscape
+
+Call `list_projects` to understand the org structure, and `wiki_stats` (with `project` when one is clearly relevant) to know where knowledge lives.
+
+### 2. Broad wiki search
+
+Run `knowledge_base` command `sections` with 2-3 phrasings -- it is semantic, so natural language works. Each hit carries the verbatim document passage that supports it: quote that rather than opening the file. Use `grep` for exact names, IDs, or phrases; if a literal `grep` misses, the wording may differ, so retry with `sections` rather than concluding the knowledge base lacks it. For "every X", counts and superlatives, list the population with `ls` (by `page_type`) or `rows` instead of extracting and grepping the documents.
+
+### 3. Ask the researcher (when available)
+
+If your client exposes `research`, call it with the question. It searches the wiki, documents, and connected services and returns a cited answer. Treat it as a starting map, not the final word.
+
+### 4. Deep read
+
+Read the top hits with `cat`, narrowest first: `section_id` from the hit, or `outline: true` to see a page's sections. Read whole pages only when you need material the hit did not point at. Pay attention to:
+- `[[links]]`, Path, Children, and "Linked from" in the output -- follow those edges
+- Page type (`decision` pages carry different weight than `research_note`)
+
+### 5. Trace provenance
+
+For key claims, use `provenance {page}` to see which sources support, contradict, or qualify each section, and `sources {page}` to see what fed the page.
+
+### 6. Follow the graph and history
+
+Use `links {page}` or `references {page}` on central pages to find related pages you missed. Use `timeline {timeline_query}` for how events unfolded, and `log {page}` only when the question is about change over time.
+
+### 7. Check for conflicts
+
+Look for citations with stance `contradicts` or `qualifies`. These are the most valuable findings -- they show where evidence disagrees.
+
+### 8. Synthesize
+
+Write up findings organized by theme, not by page. Include:
+- Key findings with page citations (title)
+- Areas of agreement across sources
+- Contradictions or open questions
+- Gaps -- what the knowledge base does NOT cover
+- Temporal context -- when information was written, whether it may be stale
+
+### 9. Recommend
+
+If research reveals gaps or stale pages, suggest specific knowledge base updates.
+
+## Cards or the original files
+
+Cards and pages are summaries written from the files a team uploaded. They tell you what is known, who owns it and where it came from, and they are the right first read. They are not the data. Go back to the original file when the answer depends on the file itself:
+
+- **You need to compute.** Totals, averages, a re-fit, a recount, a comparison across rows: the card gives you at most the numbers someone chose to write down. Compute from the source table, not from figures copied into prose.
+- **You need exact wording or a value.** A quote, a dose, a threshold, a date, a cell in a table.
+- **The card is not enough.** It is marked partial or incomplete, its `coverage` says results were cut off, it lacks the field you need, or two sources disagree (`contradicts` / `qualifies`) and you have to see which is right.
+
+How to get there:
+
+1. Find the file the claim rests on: `sources {page}` or `provenance {page}` list the cited files with their `source_ref` and file id.
+2. Read its text with the `read_file` tool (`artifact_id`, then `offset` to page through), or download the file itself for analysis: `beakr files download <artifact_id>` or `beakr.files.download(...)` in the SDK.
+3. Compute locally from the downloaded file (spreadsheet, CSV, PDF tables) and keep the calculation reproducible: say what you computed and from which rows.
+
+Then record what you learned so the next agent does not redo it: add it as a finding (`knowledge_base_write` with `action: add_finding`, or `beakr kb add-finding`) citing the original file's `source_ref`, and say in the finding that the value was computed from the file, not copied from a card. If the card itself is wrong or stale, propose an edit to it with the same citation instead.

beakr_cli-0.4.0/.claude/skills/beakr/reference/writing-pages.md

@@ -0,0 +1,168 @@
+# Writing Knowledge Base Pages
+
+Use this workflow when the user wants to create or update a page. Every change goes through `knowledge_base_write`, which stages a **proposal**; nothing is written until the user asks you to `accept_proposal`, unless the write result says the user's auto-approve is on. Two actions apply at once instead: `sort_table`, which only reorders a table, and a project or org `page_type` the verifier accepts (a global one is refused).
+
+## Before writing
+
+1. **Check for duplicates.** Search with `knowledge_base` command `sections` (and `grep` for exact names). If a page exists on this topic, read it with `cat` and update it instead of creating a new one.
+
+2. **Pick the project.** Use `list_projects` and pass the project's name or ID as `scope`. Never guess: a page title or filename is not a scope.
+
+3. **Find the right parent.** Use `suggest_parent` with `title` (and your draft as `content`) for a page you are about to create, or `ls {parent}` to walk the hierarchy. If unsure, ask the user.
+
+4. **Choose the page type: cards first.** Every project is a map of cards. One specific thing (a person, organization, product, system, model, study, decision, event) is a **card**. Before your first `new`, run `ontology` and pick the most specific card type the project has. If none fits, propose one with `page_type` rather than writing a topic. Name the card plainly (`AlphaFold`, not `DeepMind - AlphaFold`), give it a Description of 2 to 8 sentences (what it is, why it matters here, its status: its identity, not a list of facts), and grow it with `add_fact` / `add_connection` / `add_finding`, each with evidence. Common types:
+
+| Type | When to use |
+|------|-------------|
+| `person` | One person. |
+| `organization` | One company, team or department. |
+| `product`, `system`, ... | One product, system, model, study or other specific thing: use the most specific card type `ontology` lists. |
+| `decision` | One decision, with its rationale and date. |
+| `topic` | A theme, concept or field that ties several cards together (`Protein structure prediction`), never one specific system or product. Not a card; needs no card shape. |
+| `overview` | Index/section pages that tie a section together. Not a card. |
+| `research_note` | Ephemeral analysis, not canonical knowledge. |
+
+One-off messages and meetings are not cards: what they established goes on the cards of the things involved. An analysis across several cards is its own page, linked from each card with an `add_finding`.
+
+A card in two calls, a `new` and then a dated fact:
+
+```
+knowledge_base_write(
+  action="new",
+  scope="Research",
+  arguments={
+    "title": "AlphaFold",
+    "page_type": "system",
+    "summary": "DeepMind's protein-structure prediction model.",
+    "sections": [{"title": "Description", "body": "AlphaFold predicts a protein's 3D structure from its amino-acid sequence (alphafold-paper.pdf › p. 1)."}],
+    "rationale": "A system the team cites often.",
+  },
+)
+knowledge_base_write(
+  action="add_fact",
+  scope="Research",
+  arguments={
+    "page": "AlphaFold",
+    "attribute": "Release",
+    "value": "AlphaFold 2 code released as open source",
+    "when": "2021-07",
+    "evidence": "(alphafold-paper.pdf › p. 1)",
+    "rationale": "Release date from the paper.",
+  },
+)
+```
+
+`when` is when the value held in the world (`YYYY-MM-DD`, `YYYY-MM`, `YYYY-Qn` or `YYYY`), never when it was recorded.
+
+## Adding to a project-map card
+
+A map card has a Description, a Facts table (`| Attribute | Value | When | Evidence |`), a Connections table (`| Relation | To | When | Evidence |`) and dated Findings. Nuance stays in the value's own words. Add to it one row at a time; each is merged into the live card, so never resend a whole table. Its Facts, Connections and Findings rows are protected: they change only through `add_fact`, `add_connection`, `add_finding`, `edit_rows` and `sort_table`. An `edit_section` or `edit` that would change a row is refused; a `find_replace` changes the text outside the tables and reports the row matches it left for `edit_rows`. `edit_rows` takes `table` `facts`, `connections` or `findings` (a finding is named by its `date` and `text`):
+
+```
+knowledge_base_write(
+  action="add_fact",
+  scope="AMR surveillance",
+  arguments={
+    "page": "FR25-1187",
+    "attribute": "Cluster",
+    "value": "CLX-21 under SOP r7",
+    "when": "2026-06-02",
+    "evidence": "{{conversation:2026-10-06-clusters}}",
+    "citations": [{"key": "conversation:2026-10-06-clusters", "source_type": "conversation", "source_title": "Session on AMR clusters", "stance": "support", "meta": {"excerpt": "..."}}],
+    "rationale": "Re-clustering under SOP r7 moved the isolate.",
+  },
+)
+```
+
+For a source Beakr already has, `evidence` is the readable reference a read printed (`"evidence": "memo.pdf › p. 7"`); Beakr stores it as that citation. A `{{conversation:...}}` token is only for this conversation or a note, with its record in `citations` as above. A value written another way than the row already on the card (`2026-06-02` or `June 2, 2026`, `48,000` or `48000`) joins that row, and the result says so.
+
+Pass `rows=[{...}, ...]` to add several rows in one call; each item inherits the call's `evidence` and `when`. `sort_table` with `table` and `order_by` (e.g. `"attribute, when desc"`) orders a table and keeps it sorted on every later write. `add_connection` takes `relation` (a short verb phrase carrying any detail), `to` (the other page's title) and `when?`. `add_finding` takes `date`, `kind` (result, lesson, decision, question, correction), `text`, and optional `about`, `finding_scope` and `supersedes`: use it for a conclusion you reached, which is not a fact a source states. Keep attribute names stable so rows line up; a new value under the same attribute sits beside the old one as its history, and which one answers a question is decided by its `when` and the scope written in its value. Outside a project map these actions are refused on pages that are not cards; use `edit_section` there.
+
+### Keeping a card clean
+
+To change rows already on a card, use `edit_rows`: `old_rows` names each row as the card shows it (`{attribute, value}` or `{relation, to}`), and `rows` gives what replaces them, at the same place in the table:
+
+```
+knowledge_base_write(
+  action="edit_rows",
+  scope="AMR surveillance",
+  arguments={
+    "page": "FRP-SOP-0412",
+    "table": "facts",
+    "old_rows": [{"attribute": "Effective date", "value": "2026-06-11"},
+                 {"attribute": "Date effective", "value": "2026-06-11"}],
+    "rows": [{"attribute": "Effective date", "value": "2026-06-11"}],
+    "rationale": "One date recorded under two attribute names.",
+  },
+)
+```
+
+A new row that gives no `evidence` keeps every citation of the rows it replaces (and their `when`, when they agree), so merging is one call. Deleting rows outright, or leaving a replaced row's citation off, needs a `reason`. Rows that say the same thing become one row; values for different scopes, versions or times stay separate rows with the scope in the value; a row cited `contradicts` stays. Use `add_finding` only for what a row cannot hold: a conclusion or a longer explanation. A document whose versions people track by name gets a card per version under its own card.
+
+## Updating an existing page (preferred)
+
+Use `edit_section` to change one section without touching the rest of the page. Read the page first (`cat {page, outline: true}`) to get section IDs. `new_section_body` replaces that section's entire body.
+
+```
+knowledge_base_write(
+  action="edit_section",
+  scope="Platform",
+  arguments={
+    "page": "API Architecture",
+    "section_id": "sec_auth",
+    "new_section_body": "Internal services authenticate with mTLS {{conversation:2026-09-16-auth}}.",
+    "citations": [
+      {
+        "key": "conversation:2026-09-16-auth",
+        "source_type": "conversation",
+        "source_title": "Claude Code session on service auth",
+        "stance": "support",
+        "meta": {"excerpt": "We agreed to move internal services to mTLS."}
+      }
+    ],
+    "edit_note": "Record the move to mTLS",
+    "rationale": "Decision made in this session; the page still described JWT."
+  }
+)
+```
+
+To add a section, pass a new `section_id` plus `section_title` (and `after` to position it). For several changes at once, use `edit` with `patches`.
+
+## Renaming, merging and replacing text
+
+- **`mv`** renames a page. The result names the final title (`Title (1)` when the one asked for was taken) and lists the pages whose `[[links]]` still show the old title. Those links keep resolving to the renamed page; their text changes only if you stage a `find_replace` for it.
+- **`merge`** folds a duplicate (`page`) into the page to keep (`canonical`), carrying its titles over as aliases so links keep resolving. Pass `merge_sections`, the ordered list the survivor leads with (`["canonical:sec_overview", "duplicate:sec_findings"]`): only the duplicate sections it names are moved across, whole with their citations; an unnamed duplicate section is archived with the duplicate and reported in `sections_left_behind`. Read every duplicate section before leaving one out.
+- **`find_replace`** replaces text across pages; on a map card it skips the Facts, Connections and Findings rows and reports them, so change those with `edit_rows`.
+
+## Creating a page
+
+Use `new` with `title`, `page_type`, `summary`, `parent`, `rationale`, and `sections`.
+
+`sections` is the page: an ordered list of `{title, body}` objects. **Beakr writes the `<!-- sec:ID -->` markers and section IDs for you** -- do not author markers and do not pass `content`.
+
+Each section can also carry:
+- `citations`: records for the sources its body cites (see below)
+- `event_start`, `event_end`, `date_precision` (day, month, quarter, year, approx) for dated decisions, meetings, launches, incidents, and other timeline-worthy sections. `date_precision` is required whenever `event_start` is set.
+
+## Citations
+
+Cite every factual claim, table value, date, title, and relationship inline, right after it:
+
+- **A source Beakr already has:** write the readable reference a `knowledge_base` read printed for it, in parentheses, as the read did: `The rate is 21 percent (tax-memo.txt › p. 7).`, `(#deals › message 2026-03-04 14:02 UTC)`, `(ENG-12)`, `(Page Title › Section)`. Beakr stores it as that citation; a reference to something you may not cite is refused (`citation_not_citeable`). You can also list it in `citations` as `{"reference": "memo.pdf › p. 7", "stance": "support"}` or with the `source_ref` from its Sources line.
+- **A web page you read:** write its title and URL in parentheses after the claim, `(About Google DeepMind — https://deepmind.google/about/)`, or give the section's `citations` a record `{"source_type": "web", "url": "https://deepmind.google/about/", "source_title": "About Google DeepMind", "meta": {"excerpt": "the passage you rely on"}, "stance": "support"}`; to cite it inline by a name of your own, add `"key": "web:deepmind-about"` and write `{{web:deepmind-about}}` after the claim. Only `http` and `https` URLs are accepted. Beakr stores the citation as you give it and never opens the page, so quote the passage you relied on. A markdown link, `[text](https://...)`, stays a link, not a citation.
+- **This conversation, or a note** (cited for the first time): put `{{conversation:<label>}}` after the claim and give it a record in that section's `citations` with the same `key`, `source_type` `conversation` (or `agent_note`, `user_note`), a `source_title`, and `meta.excerpt` (or `meta.content` / `meta.text`). The key must start with its own source type.
+
+Set `stance` to `support`, `qualifies`, or `contradicts`. It defaults to `support`, and that default is itself a claim about the evidence. A token with no citation record is stored as a bare pointer that can never be verified.
+
+## Content conventions
+
+- Use `[[Page Title]]` to link other pages; `[[Display Text|Page Title]]` when the text differs. Check targets exist first.
+- `summary` is a one-line description of what the page is about, never a note about your edit (that is `edit_note`).
+- Include a "Related Pages" section with links to connected pages.
+- Be specific: name WHO made decisions, WHEN things happened, WHY.
+- Use tables for structured data, code blocks for config/commands.
+- Do not create stub pages -- every page should have substantive content.
+
+## After proposing
+
+A write to one section or card row (`edit_section`, `add_fact`, `add_connection`, `add_finding`, `edit_rows`) prints its proposal's id and `content_hash`. Show the user what you staged with `show_proposal`, which prints the hash again and who filed the proposal. Call `accept_proposal` only when the user explicitly asks to apply that proposal, with that hash as `reviewed_hash`: the accept then applies exactly what was shown, and a proposal that changed in between is refused (`proposal_changed`; show it again). Take the hash from the read the user reviewed, never from a fresh read made just before accepting. A proposal that changes a card's table rows is not accepted without it; it stays acceptable when the table is re-sorted or other rows change, and only a change to a row it edits supersedes it. Where the organization or project requires a person to accept what agents write, `accept_proposal` is refused (`person_review_required`) and nothing is applied, and auto-approve does not apply either: tell the user the proposal waits for them to accept in Beakr, and do not retry. `knowledge_base` command `proposals` lists pending proposals by default; `status` also takes `accepted`, `dismissed`, `superseded` (each with the reason it can no longer apply) and `resolved`, and a page that stops short names the `offset` that continues it; a proposed page does not exist in `ls`, `cat`, or search until accepted.