beakr-cli 0.2.1__tar.gz → 0.3.0__tar.gz

beakr_cli-0.3.0/.claude/commands/kb-audit.md

@@ -0,0 +1,36 @@
+Audit the Beakr knowledge base for quality issues: $ARGUMENTS
+
+If no specific focus is given, run a general health check. Pass a project's name or ID as `scope` when the user named one. Follow this procedure:
+
+1. **Get the full picture.** Call `wiki_stats` for counts and `knowledge_base` command `ls` (raise `limit` in `arguments` for a full list). Use command `ontology` to see which page types are in use.
+
+2. **Run diagnostics.** Call `knowledge_base` command `diagnostics`. It reports broken links, orphan pages, and disputes.
+
+3. **Check the graph.** Call `wiki_graph` for the most-connected pages. Look for:
+   - **Orphan pages** -- pages with no parent and no incoming links
+   - **Dead ends** -- pages with no outgoing links (isolated knowledge)
+   - **Missing index pages** -- overview pages that should tie a section together
+
+4. **Spot structural issues.** From `ls` results, look for:
+   - Duplicate or near-duplicate page titles
+   - Deeply nested hierarchies (more than 3 levels is usually too deep)
+   - Pages without a parent (command `suggest_parent` with `{"page": ...}` finds a home)
+   - Pages that look like stubs
+
+5. **Sample content quality.** Read 5-10 pages with command `cat` (start with `{"page": ..., "outline": true}`), prioritizing:
+   - Heavily edited pages (command `log`) -- is content coherent?
+   - Recently created pages (sort `ls` by `created_at`) -- stubs or unreviewed?
+   - Overview/index pages -- are they up to date with their children?
+
+6. **Check provenance.** For key pages, call command `provenance` and look for:
+   - Sections with no citations (unsourced claims)
+   - Sections with `contradicts` citations (disputed content)
+   - Excerpts marked (paraphrase) or (unverified), or sources that changed since cited
+
+7. **Report findings** organized as:
+   - **Critical** -- broken links, orphaned important pages, contradicted content
+   - **Moderate** -- missing sections, stale pages, structural issues
+   - **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.

beakr_cli-0.3.0/.claude/commands/kb-research.md

@@ -0,0 +1,29 @@
+Research the following topic using the Beakr knowledge base and provide a thorough analysis: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Discover the landscape.** Call `list_projects` to understand the available projects. Use `wiki_stats` for the whole accessible knowledge base, and with `project` when a project is clearly relevant.
+
+2. **Ask the researcher.** Call `research` with the topic as `query`. It searches the wiki, documents, and connected services and returns a cited answer. Use it as a starting map.
+
+3. **Broad search.** Run `knowledge_base` command `sections` with `{"query": ...}` using 2-3 phrasings in parallel. Use command `grep` with `{"query": ...}` for exact names or IDs. If a literal grep misses, retry with `sections` before concluding the topic is not covered.
+
+4. **Deep read.** Read the top 5-10 most relevant hits with command `cat`, using `{"page": ..., "section_id": ...}` when a hit points at a section and `{"page": ..., "outline": true}` to see a page's structure. Read in parallel. Pay attention to:
+   - Section content and structure
+   - `[[links]]`, Children, and "Linked from" to follow
+   - Page type (decision pages have different weight than research_notes)
+
+5. **Trace provenance.** For key claims, use command `provenance` with `{"page": ...}` to see which sources support, contradict, or qualify each section. Use command `sources` to see what raw documents fed each page.
+
+6. **Follow the graph.** Use command `links` or `references` with `{"page": ...}` on central pages to discover related pages you may have missed. Use command `timeline` with `{"timeline_query": ...}` to see how events unfolded, and `log` 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 the 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 that it should
+   - Temporal context -- when information was written, whether it may be stale
+
+9. **Recommend.** If the research reveals gaps or stale pages, suggest specific knowledge base updates. Offer to propose pages or edits if appropriate.

beakr_cli-0.3.0/.claude/commands/kb-search.md

@@ -0,0 +1,17 @@
+Search the Beakr knowledge base for information about: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Discover scope.** If the user mentioned a specific project, call `list_projects` and pass that project's name or ID as `scope`. Otherwise search everything the user can see (omit `scope`).
+
+2. **Search broadly.** Run `knowledge_base` with command `sections` and `arguments: {"query": ...}`; it is semantic, so try one or two phrasings in parallel. For exact names, IDs, or phrases, also run command `grep` with `{"query": ...}`.
+
+3. **Read the top hits.** For the most relevant results (up to 3-5), call `knowledge_base` command `cat` with `{"page": ..., "section_id": ...}` from the hit. Read the whole page only when you need material outside that section. Do these reads in parallel.
+
+4. **Follow links.** If the pages contain `[[links]]` to other relevant pages, read those too. Use command `links` with `{"page": ...}` to find pages that reference a key page.
+
+5. **Check provenance if needed.** If the user needs to know where information came from, use command `sources` or `provenance` with `{"page": ...}`.
+
+6. **Synthesize and cite.** Present findings with page titles so the user can navigate to them. Quote specific sections when relevant. Note any contradictions found in provenance (stance: contradicts/qualifies) and any excerpt marked (paraphrase) or (unverified).
+
+Do NOT just return search results -- read the actual pages and answer the question.

beakr_cli-0.3.0/.claude/commands/kb-write.md

@@ -0,0 +1,30 @@
+Create or update a knowledge base page about: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Check for duplicates.** Search with `knowledge_base` command `sections` and `{"query": ...}` across all accessible projects (also `grep` for exact names). If a page already exists on this topic, read it with command `cat` and update it rather than creating a new one.
+
+2. **Pick the project.** Call `list_projects` and pass the target project's name or ID as `scope` on every call below. The personal project is listed with type `personal`. Never guess a scope.
+
+3. **Find the right parent.** For a new page, call command `suggest_parent` with `{"title": ..., "content": <your draft>}`, or walk the hierarchy with command `ls` and `{"parent": ...}`. If unsure, ask the user.
+
+4. **Choose the page type.** Run command `ontology` for the active types. Common ones: `topic` (most common), `person`, `organization`, `decision`, `meeting`, `overview` (index/section pages), `research_note` (ephemeral analysis).
+
+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`.
+   - 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.
+   - Include a "Related Pages" section at the bottom.
+   - Write for a reader with no prior context: name WHO made decisions, WHEN things happened, WHY.
+   - Use tables for structured data and code blocks for config/commands.
+
+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.
+
+7. **Review.** Show the result with `show_proposal`. Call `accept_proposal` only when the user explicitly asks to apply it.
+
+Do NOT create stub pages. Every page should have substantive content.

{beakr_cli-0.2.1 → beakr_cli-0.3.0}/.claude/skills/beakr/SKILL.md

@@ -24,7 +24,7 @@ You are not just a read interface. When the conversation produces something dura
 **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 `kb_search` first
+- **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:**
@@ -45,36 +45,50 @@ You are not just a read interface. When the conversation produces something dura
 - **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.
 - One capture offer per significant thread — don't pepper the user.
-- Cite the current session as `conversation:<short-id>` with `meta.excerpt` so the source is traceable.
+- Cite the current session as a `conversation` source with `meta.excerpt` so it is traceable.
 
-## Core tools
+## Tools
 
 | Tool | When to use |
 |------|-------------|
-| `research` | First choice for broad questions. Searches knowledge base, docs, Slack, Gmail, Calendar, Jira in one call. Returns cited answers. |
-| `kb_search` | Find specific pages by semantic or keyword search. |
-| `kb_cat` | Read a page's full content by slug, title, or UUID. |
-| `kb_ls` | Browse pages. Filter by type, parent, or scope. |
-| `kb_timeline` | Find decisions, meetings, and events by date range. |
-| `kb_graph` | Understand how pages connect. Shows top linked pages. |
+| `research` | First choice for broad questions. Searches the knowledge base, documents, and connected services (Slack, Gmail, Calendar, Jira...) in one call. Returns a cited answer. |
+| `knowledge_base` | Every read over the wiki, chosen by `command`: `sections`, `grep`, `ls`, `cat`, `hover`, `links`, `references`, `timeline`, `provenance`, `blame`, `sources`, `log`, `diff`, `show`, `ontology`, `suggest_parent`, `diagnostics`, `completions`, `proposals`. |
+| `knowledge_base_write` | Every change, chosen by `action`: `edit_section`, `new`, `edit`, `find_replace`, `mv`, `archive`, `merge`, `copy`, `page_type`. Always stages a proposal. |
+| `show_proposal` / `accept_proposal` / `dismiss_proposal` | Review a staged proposal; accept only when the user explicitly asks. |
+| `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. |
+| `beakr_version` / `update_beakr` | Check for a newer Beakr release; update only when the user asks. |
+
+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).
 
 ## Quick decision tree
 
 ```
 User asks a question about their org
-  → Use `research` (it searches everything)
+  → research(query=...)
+
+User asks about a specific fact, decision, or page
+  → knowledge_base sections {query}, then cat {page, section_id} on the best hit
 
-User asks about a specific page
-  → Use `kb_cat` with the page title/slug
+User wants an exact name, ID, or phrase
+  → knowledge_base grep {query}
 
-User wants to browse or list pages
-  → Use `kb_ls` (optionally with --type, --roots, --parent)
+User wants to browse pages
+  → knowledge_base ls {parent?, page_type?, sort_by?}
 
-User wants to know what happened on a date
-  → Use `kb_timeline` with date range
+User wants to know what happened when
+  → knowledge_base timeline {timeline_query?, start_date?, end_date?}
 
 User wants to verify sources for a claim
-  → Use `kb_provenance` or `kb_blame` on the relevant page
+  → knowledge_base provenance {page} or blame {page}
 
 User wants to create/update a page
   → See [reference/writing-pages.md](reference/writing-pages.md)
@@ -85,33 +99,26 @@ User wants to audit knowledge base quality
 
 ## Scoping
 
-All tools accept an optional `project` parameter:
-- Omit it to search across the entire organization
-- Pass a project ID to scope results (use `list_projects` to discover IDs)
-- Pass `personal_only=true` to limit to the user's personal project
+- `knowledge_base` and `knowledge_base_write` take `scope`: a project name or ID. Omit it on reads to search everything the user can see.
+- `research`, `wiki_stats`, and `wiki_graph` take `project` (a project ID).
+- 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:
 - Include the page title so the user can find it
-- For `research` results, the response includes numbered citations -- present them
-- For claims that need verification, use `kb_provenance` to show supporting/contradicting sources
-- When writing wiki pages, put inline citation tokens like `{{rag:abc123}}` or
-  `{{!rag:abc123}}` immediately after every factual claim, table row/value,
-  date, title, and relationship. Also include the same keys in
-  `sections[].citations` with `support`, `qualifies`, or `contradicts` stance.
-  Add `event_start`, `event_end`, and `date_precision` for dated decisions,
-  meetings, milestones, and other timeline-worthy sections. For current-session
-  or other not-yet-indexed sources, cite a stable key with `source_type`
-  `conversation`, `agent_note`, or `user_note`, plus `source_title` and
-  `meta.excerpt`, `meta.content`, or `meta.text`.
+- For `research` results, the response includes numbered citations with their `{{token}}` keys -- 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 inline tokens and citation records
 
 ## Page references
 
-Pages can be referenced by any of:
-- UUID (exact match)
-- Slug (exact match, e.g., `api-design`)
-- Title (search, e.g., `"API Design"`)
+`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
 

{beakr_cli-0.2.1 → beakr_cli-0.3.0}/.claude/skills/beakr/examples/answer-org-question.md

@@ -6,25 +6,26 @@
 ## Workflow
 
 ### Step 1: Research
-Call `research` with query "who owns the onboarding flow":
+Call `research` with the question:
 
 ```
 research(query="who owns the onboarding flow")
 ```
 
-The response returns a cited answer mentioning Sarah Chen [1] and links to the relevant page.
+The response returns a cited answer mentioning Sarah Chen [1] and the pages it drew on.
 
 ### Step 2: Verify if needed
-If the user wants more detail, read the specific page:
+If the user wants more detail, find the exact section and read just that:
 
 ```
-kb_cat("onboarding-architecture")
+knowledge_base(command="sections", arguments={"query": "onboarding flow owner"})
+knowledge_base(command="cat", arguments={"page": "Onboarding Architecture", "section_id": "sec_ownership"})
 ```
 
 ### Step 3: Present
-"Based on the knowledge base, Sarah Chen owns the onboarding flow [onboarding-architecture]. She took ownership in Q1 2026 as part of the platform team reorganization [team-structure]."
+"Based on the knowledge base, Sarah Chen owns the onboarding flow (Onboarding Architecture). She took ownership in Q1 2026 as part of the platform team reorganization (Team Structure)."
 
 ## Key points
 - Start with `research` -- it searches everything in one call
-- Always cite the page title/slug
-- If the answer involves people, check for a `person` page with `kb_cat`
+- Always cite the page title
+- If the answer involves people, check for a `person` page with `sections {query, page_type: "person"}`

beakr_cli-0.3.0/.claude/skills/beakr/examples/research-topic.md

@@ -0,0 +1,49 @@
+# Example: Deep research on API redesign
+
+## User prompt
+"Research everything we know about the API redesign and summarize the current state"
+
+## Workflow
+
+### Step 1: Broad search (in parallel)
+```
+knowledge_base(command="sections", arguments={"query": "API redesign"})
+knowledge_base(command="sections", arguments={"query": "API architecture changes"})
+knowledge_base(command="grep", arguments={"query": "v2 migration"})
+```
+
+### Step 2: Read top hits (in parallel, narrowest read first)
+```
+knowledge_base(command="cat", arguments={"page": "API Redesign Decision"})
+knowledge_base(command="cat", arguments={"page": "API Architecture", "section_id": "sec_current_state"})
+knowledge_base(command="cat", arguments={"page": "V2 Migration Plan", "outline": true})
+```
+
+### Step 3: Check timeline
+```
+knowledge_base(command="timeline", arguments={"timeline_query": "API redesign", "start_date": "2026-01-01"})
+```
+
+### Step 4: Trace provenance on key claims
+```
+knowledge_base(command="provenance", arguments={"page": "API Redesign Decision"})
+```
+
+### Step 5: Follow links
+```
+knowledge_base(command="links", arguments={"page": "API Architecture"})
+```
+
+### Step 6: Synthesize
+Present findings by theme:
+- **Decision**: The team decided to migrate to v2 in January 2026 (API Redesign Decision)
+- **Current state**: Migration is 60% complete per the March update (V2 Migration Plan)
+- **Open questions**: Authentication approach still under discussion -- two proposals exist with contradicting provenance (API Architecture)
+- **Gap**: No page covers the data migration strategy
+
+## Key points
+- Use multiple phrasings to cast a wide net; `sections` for meaning, `grep` for exact terms
+- Read in parallel, and read sections rather than whole pages when a hit points at one
+- Check provenance to surface contradictions
+- Organize findings by theme, not by page
+- Call out gaps explicitly

beakr_cli-0.3.0/.claude/skills/beakr/examples/write-decision-page.md

@@ -0,0 +1,91 @@
+# Example: Creating a decision record
+
+## User prompt
+"Document our decision to switch from REST to GraphQL for the internal API"
+
+## Workflow
+
+### Step 1: Check for duplicates
+```
+knowledge_base(command="sections", arguments={"query": "REST to GraphQL decision internal API"})
+```
+No existing page found.
+
+### Step 2: Pick the project and parent
+```
+list_projects()
+knowledge_base(command="suggest_parent", scope="Platform", arguments={"title": "Internal API: REST to GraphQL", "content": "... draft with [[API Architecture]] links ..."})
+```
+Suggested parent: "API Architecture".
+
+### Step 3: Gather sources
+```
+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`.
+
+### Step 4: Stage the page
+
+```
+knowledge_base_write(
+  action="new",
+  scope="Platform",
+  arguments={
+    "title": "Internal API: REST to GraphQL",
+    "page_type": "decision",
+    "summary": "Decision to move internal service-to-service APIs from REST to GraphQL.",
+    "parent": "API Architecture",
+    "rationale": "The user asked to record this decision; no existing page covers it.",
+    "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"}
+        ]
+      },
+      {
+        "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}}.",
+        "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",
+            "source_title": "Claude Code session on API traffic",
+            "stance": "support",
+            "meta": {"excerpt": "Traffic analysis showed GraphQL would cut over-fetching by about 60%."}
+          }
+        ]
+      },
+      {
+        "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"}
+        ]
+      },
+      {
+        "title": "Related Pages",
+        "body": "- [[API Architecture]]\n- [[Platform Team]]"
+      }
+    ]
+  }
+)
+```
+
+### Step 5: Review with the user
+```
+show_proposal(proposal_id="...")
+```
+Call `accept_proposal` only after the user explicitly says to apply it.
+
+## 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`
+- Link related pages with `[[Page Title]]`

beakr_cli-0.3.0/.claude/skills/beakr/reference/auditing.md

@@ -0,0 +1,54 @@
+# Knowledge Base Audit
+
+Use this workflow to check knowledge base quality and find issues.
+
+## Procedure
+
+### 1. Get the full picture
+
+Call `wiki_stats` for counts and `knowledge_base` command `ls` to list pages (raise `limit` for a full list). Use `ontology` to see which page types the org uses.
+
+### 2. Run diagnostics
+
+Call `knowledge_base` command `diagnostics`. It reports broken links, orphan pages, and disputes directly.
+
+### 3. Check the graph
+
+Call `wiki_graph` for the most-connected pages. Look for:
+- **Orphan pages** -- no parent and no incoming links
+- **Dead ends** -- pages with no outgoing links (isolated knowledge)
+- **Missing index pages** -- overview pages that should tie sections together
+
+Use `links {page}` or `references {page}` to inspect a specific page's neighborhood.
+
+### 4. Spot structural issues
+
+From `ls` results, look for:
+- Duplicate or near-duplicate page titles (fix with `merge`, 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
+
+### 5. Sample content quality
+
+Read 5-10 pages with `cat {page, outline: true}` first, then the sections that matter. Prioritize:
+- Heavily edited pages (`log {page}`) -- is the content coherent?
+- Recently created pages -- are they stubs or unreviewed?
+- Overview/index pages -- are they up to date with their children?
+
+### 6. Check provenance
+
+For key pages, call `provenance {page}` and look for:
+- Sections with no citations (unsourced claims)
+- Sections with `contradicts` citations (disputed content)
+- Excerpts marked `(paraphrase)` or `(unverified)`, or sources marked "source changed since cited"
+
+### 7. Report findings
+
+Organize by severity:
+- **Critical** -- broken links, orphaned important pages, contradicted content
+- **Moderate** -- missing sections, stale pages, structural issues
+- **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.

beakr_cli-0.3.0/.claude/skills/beakr/reference/provenance.md

@@ -0,0 +1,58 @@
+# Understanding Provenance
+
+Provenance tracks where knowledge base content came from and how well-supported each claim is. All three views are `knowledge_base` commands.
+
+## Commands
+
+### blame
+Paragraph-level source attribution. Use to answer "where did this paragraph come from?"
+
+```
+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.
+
+```
+knowledge_base(command="sources", arguments={"page": "API Design"})
+```
+
+Structured results carry `source_ref`, filename, provider, URL/path, excerpt, and locator for each source. Reuse `source_ref` when citing that source in a write.
+
+### provenance
+Per-section citation rollups with stance. The most useful view for judging a claim.
+
+```
+knowledge_base(command="provenance", arguments={"page": "API Design"})
+```
+
+Each citation carries a stance:
+- **support** -- the source confirms the claim
+- **contradicts** -- the source disagrees with the claim
+- **qualifies** -- the source adds nuance or conditions to the claim
+
+## Reading evidence labels
+
+- An unmarked excerpt is a verbatim quote from the source.
+- `(normalized)` is the source's words with whitespace or formatting normalized.
+- `(paraphrase)` is the compiler's wording, not the source's.
+- `(human asserted)` was supplied by a person without checking the source text.
+- `(unverified)` was never checked against the source.
+- "source changed since cited" means the source has a newer version than the one the claim was checked against.
+
+Open the source (its `url`) before quoting a paraphrase or unverified excerpt, or before resting a conclusion on it.
+
+## When to use
+
+- User asks "where did this information come from?"
+- User questions the accuracy of a claim
+- You need to verify before presenting information as fact
+- Auditing page quality (see [auditing.md](auditing.md))
+
+## Interpreting stances
+
+- Multiple `support` citations = high confidence
+- A `contradicts` citation = flag it to the user, present both sides
+- A `qualifies` citation = include the nuance in your response
+- No citations on a section = unsourced, note this to the user

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

@@ -0,0 +1,48 @@
+# 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. Ask the researcher
+
+Call `research` 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.
+
+### 3. Broad wiki search
+
+Run `knowledge_base` command `sections` with 2-3 phrasings in parallel -- it is semantic, so natural language works. 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.
+
+### 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.