beakr-cli 0.1.0__py3-none-any.whl

beakr_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Beakr CLI -- command-line and MCP server for Beakr's knowledge base."""
+
+__version__ = "0.1.0"

beakr_cli/assets/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. Follow this procedure:
+
+1. **Get the full picture.** Call `kb_ls --all` (or `kb_ls` per space) to get every page. Call `kb_stats` per space for counts.
+
+2. **Check the graph.** Call `kb_graph` to get all nodes and edges. Look for:
+   - **Orphan pages** -- pages with no parent and no incoming links
+   - **Broken links** -- `[[links]]` that don't resolve to any page
+   - **Dead ends** -- pages with no outgoing links (isolated knowledge)
+   - **Missing index pages** -- overview pages that should tie a section together
+
+3. **Spot structural issues.** From `kb_ls` results, look for:
+   - Duplicate or near-duplicate page titles
+   - Pages with slug collisions (same slug across different scopes)
+   - Deeply nested hierarchies (more than 3 levels is usually too deep)
+   - Pages without a parent (should they be under a section?)
+   - Pages with revision 1 that may be stubs
+
+4. **Sample content quality.** Read 5-10 pages with `kb_cat`, prioritizing:
+   - Pages with high revision counts (heavily edited -- is content coherent?)
+   - Pages with revision 1 (potentially stubs or unreviewed)
+   - Overview/index pages (are they up to date with their children?)
+
+5. **Check provenance.** For key pages, call `kb_provenance` and look for:
+   - Sections with no citations (unsourced claims)
+   - Sections with only `contradicts` citations (disputed content)
+   - Stale provenance (old sources, no recent updates)
+
+6. **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 fix issues directly using `kb_edit`, `kb_move`, or `kb_create` if the user approves.

beakr_cli/assets/commands/kb-research.md

@@ -0,0 +1,27 @@
+Research the following topic using the Beakr knowledge base and provide a thorough analysis: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Discover the landscape.** Call `list_spaces` and `list_projects` to understand the org structure. Then `kb_stats` on each space to know where the bulk of knowledge lives.
+
+2. **Broad search.** Run `kb_search` with multiple query variations in parallel across spaces. Use different phrasings -- the knowledge base uses hybrid semantic + keyword search, so both precise terms and natural language queries work.
+
+3. **Deep read.** Read the top 5-10 most relevant pages with `kb_cat` (in parallel). Pay attention to:
+   - Section content and structure
+   - `[[links]]` to follow
+   - Page type (decision pages have different weight than research_notes)
+
+4. **Trace provenance.** For key claims, use `kb_provenance` to see which sources support, contradict, or qualify each section. Use `kb_sources` to understand what raw documents fed each page.
+
+5. **Follow the graph.** Use `kb_links` (backlinks) on central pages to discover related pages you may have missed. Use `kb_log` to see revision history and understand how knowledge evolved.
+
+6. **Check for conflicts.** Look for provenance entries with stance `contradicts` or `qualifies`. These are the most valuable findings -- they show where the evidence disagrees.
+
+7. **Synthesize.** Write up findings organized by theme, not by page. Include:
+   - Key findings with page citations (title + slug)
+   - 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
+
+8. **Recommend.** If the research reveals gaps or stale pages, suggest specific knowledge base updates. Offer to create or edit pages if appropriate.

beakr_cli/assets/commands/kb-search.md

@@ -0,0 +1,17 @@
+Search the Beakr knowledge base for information about: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Discover scope.** Call `list_spaces` to see available spaces. If the user mentioned a specific space or project, use that. Otherwise search across all spaces.
+
+2. **Search in parallel.** If there are multiple spaces, launch parallel `kb_search` calls -- one per space -- with the query. Also run one unscoped (org-wide) search. This catches pages that live at org level.
+
+3. **Read the top hits.** For the most relevant results (up to 3-5 pages), call `kb_cat` to read the full content. Do these reads in parallel.
+
+4. **Follow links.** If the pages contain `[[links]]` to other relevant pages, read those too. Use `kb_links` (backlinks) to find pages that reference a key page.
+
+5. **Check provenance if needed.** If the user needs to know where information came from, use `kb_sources` or `kb_provenance` on the relevant pages.
+
+6. **Synthesize and cite.** Present findings with page titles and slugs so the user can navigate to them. Quote specific sections when relevant. Note any contradictions found in provenance (stance: contradicts/qualifies).
+
+Do NOT just return search results -- read the actual pages and answer the question.

beakr_cli/assets/commands/kb-write.md

@@ -0,0 +1,26 @@
+Create or update a knowledge base page about: $ARGUMENTS
+
+Follow this procedure:
+
+1. **Check for duplicates.** Search the knowledge base first with `kb_search` across all spaces. If a page already exists on this topic, read it with `kb_cat` and decide whether to update it (via `kb_edit`) or create a new page.
+
+2. **Find the right parent.** Use `kb_ls` with the target space to see the page hierarchy. Place the new page under the most logical parent (e.g., a topic page under an overview section). If unsure, ask the user.
+
+3. **Choose the right page type.** Pick from: `topic` (most common), `person`, `organization`, `decision`, `meeting`, `overview` (index/section pages), `research_note` (ephemeral analysis).
+
+4. **Write the content** following these conventions:
+   - Use `<!-- sec:OPAQUE_ID -->` markers before each major section (e.g., `<!-- sec:auth_overview -->`). These are required for section-level provenance tracking.
+   - Use `[[Page Title]]` syntax for cross-references to other knowledge base pages. Check that target pages exist first.
+   - Use `[[Display Text|slug]]` for links where the display text differs from the page title.
+   - Include a "Related Pages" section at the bottom with links to connected pages.
+   - Write for a reader who has no prior context -- be specific, not vague.
+   - Attribution matters: name WHO made decisions, WHEN things happened.
+   - Use tables for structured data. Use code blocks for config/commands.
+
+5. **Scope the page correctly.** Always pass the `space` parameter when creating. If the page belongs to a project, pass `project` too.
+
+6. **Create the page** with `kb_create`, providing title, content, page_type, summary, parent_page, and space/project.
+
+7. **Verify.** Read it back with `kb_cat` to confirm it rendered correctly.
+
+Do NOT create stub pages. Every page should have substantive content.

beakr_cli/assets/skills/beakr/SKILL.md

@@ -0,0 +1,85 @@
+---
+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
+
+Use the Beakr MCP tools to search, read, research, and write to the organization's knowledge base.
+
+## 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
+
+## Core 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. |
+
+## Quick decision tree
+
+```
+User asks a question about their org
+  → Use `research` (it searches everything)
+
+User asks about a specific page
+  → Use `kb_cat` with the page title/slug
+
+User wants to browse or list pages
+  → Use `kb_ls` (optionally with --type, --roots, --parent)
+
+User wants to know what happened on a date
+  → Use `kb_timeline` with date range
+
+User wants to verify sources for a claim
+  → Use `kb_provenance` or `kb_blame` on the relevant page
+
+User wants to create/update a page
+  → See [reference/writing-pages.md](reference/writing-pages.md)
+
+User wants to audit knowledge base quality
+  → See [reference/auditing.md](reference/auditing.md)
+```
+
+## 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 space
+
+## 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
+
+## 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"`)
+
+## Advanced workflows
+
+- **Deep research**: See [reference/research-workflow.md](reference/research-workflow.md)
+- **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/assets/skills/beakr/examples/answer-org-question.md

@@ -0,0 +1,30 @@
+# Example: Answering "Who owns onboarding?"
+
+## User prompt
+"Who owns the onboarding flow?"
+
+## Workflow
+
+### Step 1: Research
+Call `research` with query "who owns the onboarding flow":
+
+```
+research(query="who owns the onboarding flow")
+```
+
+The response returns a cited answer mentioning Sarah Chen [1] and links to the relevant page.
+
+### Step 2: Verify if needed
+If the user wants more detail, read the specific page:
+
+```
+kb_cat("onboarding-architecture")
+```
+
+### 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]."
+
+## 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`

beakr_cli/assets/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
+```
+kb_search(query="API redesign")
+kb_search(query="API architecture changes")
+kb_search(query="REST API migration")
+```
+
+### Step 2: Read top hits
+```
+kb_cat("api-redesign-decision")
+kb_cat("api-architecture")
+kb_cat("v2-migration-plan")
+```
+
+### Step 3: Check timeline
+```
+kb_timeline(query="API", start_date="2026-01-01")
+```
+
+### Step 4: Trace provenance on key claims
+```
+kb_provenance("api-redesign-decision")
+```
+
+### Step 5: Follow links
+```
+kb_links("api-architecture")  # what pages link here?
+```
+
+### 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 search queries to cast a wide net
+- Read pages in parallel for speed
+- Check provenance to surface contradictions
+- Organize findings by theme, not by page
+- Call out gaps explicitly

beakr_cli/assets/skills/beakr/examples/write-decision-page.md

@@ -0,0 +1,89 @@
+# 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
+```
+kb_search(query="REST GraphQL decision internal API")
+```
+No existing page found.
+
+### Step 2: Find parent
+```
+kb_ls(page_type="overview")
+```
+Found "API Architecture" overview page -- use as parent.
+
+### Step 3: Research context
+```
+research(query="internal API architecture GraphQL REST")
+```
+Gather background from existing pages to include context.
+
+### Step 4: Write the page
+
+Create with type `decision`:
+
+```markdown
+<!-- sec:summary -->
+## Summary
+
+The engineering team decided to migrate the internal API from REST to GraphQL,
+effective Q2 2026. This affects service-to-service communication only; the
+public API remains REST.
+
+<!-- sec:context -->
+## Context
+
+The internal API serves 12 backend services with ~40 endpoints. Pain points
+included over-fetching, versioning complexity, and inconsistent error handling.
+See [[API Architecture]] for the current state.
+
+<!-- sec:decision -->
+## Decision
+
+**Date:** 2026-03-15
+**Decision maker:** Sarah Chen (CTO)
+**Participants:** Platform team, Backend leads
+
+Adopt GraphQL for internal service communication using Apollo Federation.
+Key factors:
+- Reduces over-fetching by 60% based on traffic analysis
+- Single schema eliminates versioning overhead
+- TypeScript codegen provides type safety end-to-end
+
+<!-- sec:alternatives -->
+## Alternatives considered
+
+1. **Keep REST, add OpenAPI codegen** -- Lower migration cost but doesn't solve over-fetching
+2. **gRPC** -- Better performance but steeper learning curve and weaker tooling for our stack
+3. **tRPC** -- Good DX but limited to TypeScript services only
+
+<!-- sec:consequences -->
+## Consequences
+
+- 3-month migration timeline for core services
+- Training needed for team members new to GraphQL
+- Monitoring approach changes (per-field metrics vs per-endpoint)
+
+## Related Pages
+
+- [[API Architecture]]
+- [[Platform Team]]
+- [[Q2 2026 Roadmap]]
+```
+
+### Step 5: Verify
+```
+kb_cat("rest-to-graphql-decision")
+```
+
+## Key points
+- Always use `decision` page type for decision records
+- Include date, decision maker, and participants
+- Document alternatives that were considered and why they were rejected
+- Link to related pages with `[[Page Title]]` syntax
+- Add section markers for provenance tracking

beakr_cli/assets/skills/beakr/reference/auditing.md

@@ -0,0 +1,46 @@
+# Knowledge Base Audit
+
+Use this workflow to check knowledge base quality and find issues.
+
+## Procedure
+
+### 1. Get the full picture
+
+Call `kb_ls` to get every page. Call `kb_stats` for counts.
+
+### 2. Check the graph
+
+Call `kb_graph` to get nodes and edges. 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
+
+### 3. Spot structural issues
+
+From `kb_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 (should they be under a section?)
+- Pages with revision 1 that may be stubs
+
+### 4. Sample content quality
+
+Read 5-10 pages with `kb_cat`, prioritizing:
+- Pages with high revision counts (heavily edited -- is content coherent?)
+- Pages with revision 1 (potentially stubs or unreviewed)
+- Overview/index pages (are they up to date with their children?)
+
+### 5. Check provenance
+
+For key pages, call `kb_provenance` and look for:
+- Sections with no citations (unsourced claims)
+- Sections with only `contradicts` citations (disputed content)
+- Stale provenance (old sources, no recent updates)
+
+### 6. 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

beakr_cli/assets/skills/beakr/reference/provenance.md

@@ -0,0 +1,49 @@
+# Understanding Provenance
+
+Provenance tracks where knowledge base content came from and how confident the claims are.
+
+## Tools
+
+### kb_blame
+Shows paragraph-level source attribution. Use to answer "where did this paragraph come from?"
+
+```
+kb_blame "page-slug"
+```
+
+Returns: revision number, source title, and text excerpt for each paragraph.
+
+### kb_sources
+Lists all source documents that contributed to a page.
+
+```
+kb_sources "page-slug"
+```
+
+Returns: source type, title, and ID for each source.
+
+### kb_provenance
+Shows section-level citations with stance. This is the most powerful provenance tool.
+
+```
+kb_provenance "page-slug"
+```
+
+Returns citations organized by section, each with a stance:
+- **supports** -- the source confirms the claim
+- **contradicts** -- the source disagrees with the claim
+- **qualifies** -- the source adds nuance or conditions to the claim
+
+## 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 `supports` 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/assets/skills/beakr/reference/research-workflow.md

@@ -0,0 +1,45 @@
+# 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. Then `kb_stats` on relevant projects to know where knowledge lives.
+
+### 2. Broad search
+
+Run `kb_search` with multiple query variations in parallel. The knowledge base uses hybrid semantic + keyword search, so both precise terms and natural language work. Try 2-3 phrasings.
+
+### 3. Deep read
+
+Read the top 5-10 most relevant pages with `kb_cat` (in parallel). Pay attention to:
+- Section content and structure
+- `[[links]]` to follow for related pages
+- Page type (`decision` pages carry different weight than `research_note`)
+
+### 4. Trace provenance
+
+For key claims, use `kb_provenance` to see which sources support, contradict, or qualify each section. Use `kb_sources` to understand what raw documents fed each page.
+
+### 5. Follow the graph
+
+Use `kb_links` (backlinks) on central pages to discover related pages you may have missed. Use `kb_log` to see revision history and understand how knowledge evolved.
+
+### 6. Check for conflicts
+
+Look for provenance entries with stance `contradicts` or `qualifies`. These are the most valuable findings -- they show where evidence disagrees.
+
+### 7. Synthesize
+
+Write up findings organized by theme, not by page. Include:
+- Key findings with page citations (title + slug)
+- 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
+
+### 8. Recommend
+
+If research reveals gaps or stale pages, suggest specific knowledge base updates.

beakr_cli/assets/skills/beakr/reference/writing-pages.md

@@ -0,0 +1,53 @@
+# Writing Knowledge Base Pages
+
+Use this workflow when the user wants to create or update a page.
+
+## Before writing
+
+1. **Check for duplicates.** Search with `kb_search` across all spaces. If a page exists on this topic, read it with `kb_cat` and decide whether to update or create new.
+
+2. **Find the right parent.** Use `kb_ls` to see the page hierarchy. Place the new page under the most logical parent. If unsure, ask the user.
+
+3. **Choose the right page type:**
+
+| Type | When to use |
+|------|-------------|
+| `topic` | Most common. Concepts, systems, processes. |
+| `person` | People profiles. |
+| `organization` | Companies, teams, departments. |
+| `decision` | Decisions with rationale and date. |
+| `meeting` | Meeting notes with attendees and outcomes. |
+| `overview` | Index/section pages that tie a section together. |
+| `research_note` | Ephemeral analysis, not canonical knowledge. |
+
+## Content conventions
+
+### Section markers (required)
+Add `<!-- sec:OPAQUE_ID -->` before each major section. These enable section-level provenance tracking.
+
+```markdown
+<!-- sec:auth_overview -->
+## Authentication Overview
+
+Our authentication uses JWT tokens issued by Clerk...
+
+<!-- sec:auth_flow -->
+## Authentication Flow
+
+1. User submits credentials to Clerk...
+```
+
+### Cross-references
+Use `[[Page Title]]` to link to other KB pages. Verify targets exist first with `kb_search`.
+
+Use `[[Display Text|slug]]` when display text differs from the page title.
+
+### Structure
+- Include a "Related Pages" section at the bottom 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 writing
+
+Read the page back with `kb_cat` to verify it rendered correctly.