@simpleapps-com/augur-skills 0.0.2 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "0.0.2",
+  "version": "0.0.13",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/augur-api/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: augur-api
+description: Augur API integration via MCP. Covers service discovery, CRUD operations across all 27 Augur microservices, and credential resolution. Use when querying or modifying Augur data (contacts, transactions, inventory, etc.).
+---
+
+# Augur API
+
+MCP server exposing all 27 Augur microservices through 6 generic tools.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `augur_discover` | List services or endpoints for a service |
+| `augur_list` | List records (GET collection) |
+| `augur_get` | Get single record by ID |
+| `augur_create` | Create record (POST) |
+| `augur_update` | Update record (PUT) |
+| `augur_delete` | Delete record (DELETE) |
+
+## Usage Pattern
+
+Always start with discovery:
+
+1. `augur_discover()` — lists all available services
+2. `augur_discover(service="<name>")` — lists endpoints for a specific service
+3. Use `augur_list`, `augur_get`, `augur_create`, `augur_update`, `augur_delete` for CRUD
+
+Do NOT hardcode service names or endpoints. Use `augur_discover` to find them at runtime.
+
+## Authentication
+
+Credentials resolve automatically — no setup needed if running from a project directory with a `protected/` folder containing credentials.
+
+Resolution order (first match wins):
+
+1. **Env vars** — `AUGUR_TOKEN` + `AUGUR_SITE_ID`
+2. **Explicit file** — `AUGUR_CREDS_FILE` env var pointing to a JSON file
+3. **Ancestor walk** — walks up from cwd looking for `protected/*.json`
+4. **Default file** — `~/.simpleapps/augur-api.json`
+
+Credentials file format: `{"siteId": "...", "jwt": "..."}`
+
+The ancestor walk means client project directories with `protected/<client>.json` just work.
+
+## When Auth Fails
+
+If tools return authentication errors:
+- Check for `protected/*.json` in the project directory or any ancestor
+- Verify the file contains valid `siteId` and `jwt` keys
+- Fallback: set `AUGUR_TOKEN` and `AUGUR_SITE_ID` env vars

package/skills/simpleapps/fyxer/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: fyxer
+description: Fyxer AI meeting recording integration. Covers extraction, local caching, and posting to downstream services. Use when processing Fyxer recordings or meeting transcripts.
+---
+
+# Fyxer
+
+Fyxer AI records and summarizes meetings. This skill covers extracting data from Fyxer and routing it to other services.
+
+## Fyxer URLs
+
+Recording page: `https://app.fyxer.com/call-recordings/<meeting-uuid>:<calendar-event-id>`
+
+The URL path after `/call-recordings/` contains two parts separated by a colon:
+- **Meeting UUID** (before colon): `52f0cf2b-fdb8-4e95-8b01-2afb6d367c69`
+- **Calendar event ID** (after colon): `2fg5k3v3hffl91dnuqauc15suk_20260119T190000Z`
+
+Use only the **meeting UUID** for cache folders, duplicate checks, and frontmatter.
+
+Each recording has two tabs:
+- **Summary** — AI-generated summary with section headings, participants, action items. Has "Copy summary" and "Download PDF" buttons.
+- **Transcript** — Speaker-attributed, timestamped full transcript. Has "Copy transcript" and "Download transcript" buttons.
+
+## Local Cache
+
+All extracted data is cached at `~/.simpleapps/fyxer/<meeting-uuid>/`:
+
+```
+summary.txt     - raw Fyxer summary (from Summary tab)
+transcript.txt  - raw Fyxer transcript (from Transcript tab)
+message.txt     - assembled output (generated by downstream processes, e.g. basecamp.md)
+```
+
+Cache is populated via Chrome extraction (see below) and reused across processes.
+
+## Chrome Extraction
+
+Only needed when local cache files are missing.
+
+### Extract transcript
+
+Click the **Transcript** tab. Extraction methods (in order of preference):
+
+1. **"Download transcript" button** (BEST) — Downloads a `.txt` file to `~/Downloads/`. Complete content, no truncation. Copy to cache dir, then delete the download.
+2. **"Copy transcript" button** + `pbpaste` — Copies to system clipboard. Write to disk: `pbpaste > transcript.txt`. Reliable but requires clipboard access.
+3. **`get_page_text`** — UNRELIABLE. Only captures visible/partial content. Missed most of a 30-minute transcript in testing. DO NOT USE for transcripts.
+
+Save to `~/.simpleapps/fyxer/<meeting-uuid>/transcript.txt`.
+
+### Extract summary
+
+The Summary tab is the default view. Extraction methods (in order of preference):
+
+1. **"Copy summary" button** + `pbpaste` (BEST) — Copies markdown to clipboard. Write to disk: `pbpaste > summary.txt`. Summaries are short (~1,700 chars) so this works well.
+2. **`get_page_text`** — Works for short summaries but mixes in page chrome. Not recommended.
+
+Save to `~/.simpleapps/fyxer/<meeting-uuid>/summary.txt`.
+
+### Extract participants
+
+Click the **participant count dropdown** (e.g. "3 participants") in the page header to reveal attendee names and emails. Take a screenshot to read them.
+
+### Clipboard verification
+
+To verify clipboard content is complete before writing to disk:
+
+```javascript
+(async () => {
+  const text = await navigator.clipboard.readText();
+  window.__temp = text;
+  return JSON.stringify({
+    length: text.length,
+    first50: text.substring(0, 50),
+    last100: text.substring(text.length - 100)
+  });
+})()
+```
+
+Then write and verify: `pbpaste > target.txt && wc -c target.txt`
+
+**Note**: Do NOT try to read full clipboard content via JS — Chrome MCP truncates JS output at ~1,000 characters. Always use `pbpaste` to write to disk.
+
+### Download cleanup
+
+MUST clean up `~/Downloads/` after copying downloaded files to the cache directory. Fyxer names downloads like `transcript-SA_USCCO.txt`. Repeated downloads append `(1)`, `(2)`, etc.
+
+## Processes
+
+- See `basecamp.md` for posting meeting transcripts as Basecamp Discussions
+- See `basecamp-index.md` for the Fyxer Index document (duplicate detection, reconciliation)
+
+## Dependencies
+
+- Chrome browser automation (for extraction when cache is empty)

package/skills/simpleapps/fyxer/basecamp-index.md

@@ -0,0 +1,110 @@
+# Fyxer Index — Basecamp Document
+
+Each Basecamp project that receives Fyxer meeting transcripts MUST have a **Fyxer Index** document. This document serves as a fast lookup for duplicate detection and meeting history, accessible to all team members.
+
+## Document Format
+
+- **Title**: `Fyxer Index`
+- **Location**: Documents section of each Basecamp project
+- **Content**: One line per posted meeting, newest first
+
+Each line follows this format:
+
+```
+<meeting-uuid> | <date> | <message-id> | <subject>
+```
+
+Example:
+
+```
+52f0cf2b-fdb8-4e95-8b01-2afb6d367c69 | 2026-01-19 | 514789012 | Fyxer: 2026-01-19
+a1b2c3d4-e5f6-7890-abcd-ef1234567890 | 2026-02-10 | 514801234 | Fyxer: 2026-02-10
+d9e8f7a6-b5c4-3210-fedc-ba0987654321 | 2026-02-15 | 514823456 | Fyxer: 2026-02-15
+```
+
+Fields:
+
+| Field | Source |
+|-------|--------|
+| meeting-uuid | UUID from Fyxer URL (before the colon) |
+| date | Meeting date (YYYY-MM-DD) |
+| message-id | Basecamp message ID returned by `create_message` |
+| subject | Message subject as posted (e.g., `Fyxer: 2026-02-15`) |
+
+## Finding the Index
+
+```
+list_documents(project_id)
+```
+
+Scan for a document titled `Fyxer Index`. Use `get_document(project_id, document_id)` to read its contents.
+
+## Creating the Index
+
+If no `Fyxer Index` document exists in the project, create one before posting the first meeting:
+
+```
+create_document(project_id, "Fyxer Index", "")
+```
+
+This creates an empty document. The first meeting entry will be appended after posting.
+
+## Updating the Index
+
+After successfully posting a meeting transcript via `create_message`, append a new line to the index:
+
+1. Read the current index: `get_document(project_id, document_id)`
+2. Append the new entry to the content (newest first — add to the top)
+3. Update: `update_document(project_id, document_id, title="Fyxer Index", content=updated_content)`
+
+The `create_message` response includes the message ID needed for the index entry.
+
+## Duplicate Check
+
+Before posting a meeting transcript, check the index:
+
+1. Find the Fyxer Index document: `list_documents(project_id)` → scan for `Fyxer Index`
+2. Read it: `get_document(project_id, document_id)`
+3. Search the content for the meeting UUID
+4. If found → the meeting has already been posted. Inform the user and stop.
+5. If not found → safe to proceed with posting.
+
+If no Fyxer Index document exists, there are no posted meetings in this project. Proceed with posting and create the index.
+
+## Reconciliation — Missing Entries
+
+The index MAY fall out of sync if a meeting was posted without updating the index (e.g., manual posting, index creation after existing meetings). To reconcile:
+
+1. List all messages: `list_messages(project_id)`
+2. Filter for messages with `Fyxer:` in the title
+3. For each Fyxer message, call `get_message(project_id, message_id)` and extract the `fyxer-id` from the YAML frontmatter
+4. Compare against the index — add any missing entries
+5. Update the index document with the complete list
+
+Run reconciliation when:
+- The Fyxer Index document is first created in a project that already has Fyxer messages
+- The user suspects the index is incomplete
+- A duplicate check finds nothing but the user believes a meeting was already posted
+
+## Reconciliation — Orphaned Entries
+
+If an index entry references a message that no longer exists (deleted in Basecamp):
+
+1. Attempt `get_message(project_id, message_id)` for the entry
+2. If 404 → the message was deleted. Remove the entry from the index.
+3. Update the index document
+
+Only run orphan cleanup when explicitly requested by the user. Do not automatically delete index entries.
+
+## Updated Posting Process
+
+The full Fyxer → Basecamp posting process (see `basecamp.md`) now includes index management:
+
+1. **Check index** — find Fyxer Index doc, read it, search for meeting UUID
+2. **Check local cache** — if summary.txt and transcript.txt exist, skip extraction
+3. **Extract from Chrome** — if cache is missing (see `SKILL.md`)
+4. **Build message.txt** — frontmatter + transcript
+5. **Post to Basecamp** — `create_message` → capture message_id from response
+6. **Update index** — append new entry to Fyxer Index document (create doc if needed)
+
+Step 6 is new. If the index update fails after a successful post, warn the user — the message is posted but the index is stale. The user can run reconciliation later to fix it.

package/skills/simpleapps/fyxer/basecamp.md

@@ -0,0 +1,91 @@
+# Fyxer → Basecamp
+
+Post Fyxer meeting recordings as searchable Discussions in Basecamp projects.
+
+## Inputs
+
+- **Fyxer recording URL**: `https://app.fyxer.com/call-recordings/<meeting-uuid>:<calendar-event-id>`
+- **Basecamp project ID**: Target project for the Discussion
+
+## Process
+
+### 1. Check for duplicate
+
+Extract the meeting UUID from the Fyxer URL (the part before the colon).
+
+Find the **Fyxer Index** document in the project: `list_documents(project_id)` → scan for title `Fyxer Index`. If found, `get_document(project_id, document_id)` and search the content for the meeting UUID. If the UUID appears, the meeting has already been posted — inform the user and stop.
+
+If no Fyxer Index document exists, there are no tracked meetings in this project. Proceed with posting.
+
+See `basecamp-index.md` for full index format and reconciliation.
+
+### 2. Check local cache
+
+If `~/.simpleapps/fyxer/<meeting-uuid>/summary.txt` and `transcript.txt` both exist, skip to step 3. Otherwise, follow the Chrome extraction steps in `SKILL.md`.
+
+### 3. Build message.txt
+
+Parse `summary.txt` for frontmatter fields, extract participants (see `SKILL.md` participant extraction), and combine with the full transcript from `transcript.txt`:
+
+```
+---
+meeting: SA/ClientName
+date: YYYY-MM-DD
+time: HH:MM-HH:MM
+participants: Person A, Person B, Person C
+topics: Topic One, Topic Two, Topic Three
+fyxer-id: <meeting-uuid>
+---
+
+[contents of transcript.txt]
+```
+
+Frontmatter field sources:
+
+| Field | Source |
+|-------|--------|
+| meeting | Meeting title from the page header |
+| date | Recording date |
+| time | Recording time range |
+| participants | Participant dropdown (click to reveal names) |
+| topics | Section headings from the Summary |
+| fyxer-id | Meeting UUID from the URL (before the colon) |
+
+Save as `~/.simpleapps/fyxer/<meeting-uuid>/message.txt`.
+
+### 4. Post to Basecamp
+
+Use `create_message(project_id, subject, content)`:
+
+- **Subject**: `Fyxer: YYYY-MM-DD`
+- **Content**: contents of `message.txt`
+
+Capture the **message_id** from the response.
+
+### 5. Update Fyxer Index
+
+After a successful post, update the Fyxer Index document:
+
+1. If no Fyxer Index document exists, create one: `create_document(project_id, "Fyxer Index", "")`
+2. Read current content: `get_document(project_id, document_id)`
+3. Prepend a new line (newest first): `<meeting-uuid> | <date> | <message-id> | <subject>`
+4. Update: `update_document(project_id, document_id, title="Fyxer Index", content=updated_content)`
+
+If the index update fails after a successful post, warn the user. The message is posted but the index is stale. Run reconciliation later (see `basecamp-index.md`).
+
+## Format Rules
+
+- **Plain text only** — Basecamp prefers plain text over HTML
+- **YAML frontmatter** — machine-parseable so other Claude Code instances can search and parse meeting context
+- **Transcript only in body** — summary and action items belong on relevant Basecamp todos, not in this message
+- **Consistent title** — `Fyxer: YYYY-MM-DD` keeps messages uniform and sortable
+
+## Finding Posted Transcripts
+
+Check the index: `list_documents(project_id)` → find `Fyxer Index` → `get_document`
+View a specific transcript: `get_message(project_id, message_id)` using the message_id from the index
+Browse all messages: `list_messages(project_id)` — Fyxer posts use the title format `Fyxer: YYYY-MM-DD`
+
+## Dependencies
+
+- Basecamp MCP (`create_message`, `create_document`, `update_document`, `list_documents`, `get_document` tools) — see `simpleapps:workflow` skill (`basecamp.md`) for full MCP tool reference

package/skills/simpleapps/github/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: github
+description: GitHub conventions for SimpleApps. Covers org structure, local project layout, wiki-as-docs workflow, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, setting up repos, or working with GitHub wikis.
+---
+
+# GitHub
+
+## Organization
+
+All SimpleApps repos live under the **`simpleapps-com`** GitHub org.
+
+Repository pattern: `simpleapps-com/<repo-name>`
+
+## Authentication
+
+Use the `gh` CLI for all GitHub operations:
+
+```bash
+gh auth status          # Check auth status
+gh auth setup-git       # Configure gh as git credential helper
+```
+
+If `git push` fails with 401/403, run `gh auth setup-git` to fix credentials.
+
+## Key Topics
+
+- **Wiki as context** — See `wiki-as-context.md` for why the wiki is the source of truth and how to write for both humans and AI agents.
+- **Project structure** — See `project-structure.md` for the `{project}/[repo|wiki]` layout, what goes where, and wiki conventions.
+- **Issues & pull requests** — See `issues-prs.md` for issue templates, PR commands, and cross-linking with Basecamp.
+
+## Quick Reference
+
+```bash
+# Pushing
+gh auth setup-git && git push origin <branch>
+git push origin <tag>
+
+# Issues
+gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body "..."
+gh issue list --repo simpleapps-com/<repo>
+
+# PRs
+gh pr create --repo simpleapps-com/<repo> --title "title" --body "..."
+gh pr list --repo simpleapps-com/<repo>
+```

package/skills/simpleapps/github/issues-prs.md

@@ -0,0 +1,89 @@
+# Issues & Pull Requests
+
+## Issues
+
+### Creating Issues
+
+MUST always use `--repo simpleapps-com/<repo>` to target the correct org. MUST ask the user which repo to create the issue in — never assume.
+
+### Issue Title
+
+- Use conventional commit style: `fix: description`, `feat: description`, `chore: description`
+- SHOULD be a technical description, not the client's words
+- Keep under 70 characters
+
+### Issue Body
+
+Every issue MUST include these sections:
+
+```markdown
+## Problem
+What is broken, missing, or needed? Include error messages, URLs, or screenshots if relevant.
+
+## Expected Behavior
+What SHOULD happen instead? Be specific.
+
+## Acceptance Criteria
+- [ ] Concrete, testable criteria
+- [ ] Each item is independently verifiable
+
+## Context
+Any additional info: related issues, affected files, workarounds, reproduction steps.
+```
+
+For bug reports, also include:
+- **Steps to Reproduce** — numbered steps to trigger the bug
+- **Current Behavior** — what actually happens (with error messages)
+
+### Labels
+
+Use labels to categorize: `bug`, `feature`, `enhancement`
+
+### Example
+
+```bash
+gh issue create --repo simpleapps-com/<repo> \
+  --title "fix: search endpoint returns 404" \
+  --body "$(cat <<'ISSUE'
+## Problem
+The `search` MCP tool returns HTTP 404 on every query. This prevents finding content across projects.
+
+## Expected Behavior
+Search SHOULD return matching results, consistent with the Basecamp web UI.
+
+## Acceptance Criteria
+- [ ] Search returns results for known content
+- [ ] Error handling for empty results
+
+## Context
+BCX API may not expose a search endpoint. Web UI search at `/search?q=...` works.
+ISSUE
+)"
+```
+
+### Managing Issues
+
+```bash
+gh issue list --repo simpleapps-com/<repo>                    # List open issues
+gh issue list --repo simpleapps-com/<repo> --state all        # Include closed
+gh issue view <number> --repo simpleapps-com/<repo>           # View issue details
+gh issue close <number> --repo simpleapps-com/<repo>          # Close issue
+gh issue close <number> --repo simpleapps-com/<repo> --comment "message"  # Close with comment
+```
+
+### Closing via Commit
+
+Include `Closes #N` in the commit message body to auto-close issues when pushed.
+
+## Pull Requests
+
+```bash
+gh pr create --repo simpleapps-com/<repo> --title "title" --body "description"
+gh pr list --repo simpleapps-com/<repo>
+gh pr view <number> --repo simpleapps-com/<repo>
+gh pr merge <number> --repo simpleapps-com/<repo>
+```
+
+## Cross-Linking with Basecamp
+
+When working on client tasks that originate in Basecamp, see the `simpleapps:workflow` skill for the full Basecamp-to-GitHub cross-linking process.

package/skills/simpleapps/github/project-structure.md

@@ -0,0 +1,142 @@
+# Project Structure & Wiki Workflow
+
+## Local Layout
+
+Every project MUST use this layout:
+
+```
+{project}/
+├── repo/        # Main git repo (simpleapps-com/<name>.git)
+├── wiki/        # GitHub wiki repo (simpleapps-com/<name>.wiki.git)
+├── wip/         # Work-in-progress files for active tasks (not in git)
+└── protected/   # Secrets and credentials for dev testing (not in git)
+```
+
+The parent `{project}/` directory is NOT a git repo — it's a local wrapper that keeps the code repo and wiki side-by-side. The `wip/` and `protected/` directories sit outside both git trees so their contents can never be accidentally committed.
+
+## Why This Pattern
+
+- GitHub wikis are separate git repos. Cloning them alongside the code keeps everything local and searchable.
+- AI agents (Claude Code) can `Read` wiki files from disk instantly instead of fetching URLs.
+- The wiki becomes the **source of truth for dev docs**. The repo stays focused on product code.
+
+## Setting Up a New Project
+
+```bash
+mkdir {project}
+cd {project}
+git clone https://github.com/simpleapps-com/<name>.git repo
+git clone https://github.com/simpleapps-com/<name>.wiki.git wiki
+```
+
+If the wiki repo doesn't exist yet, create it by adding any page via the GitHub wiki UI first, then clone.
+
+## What Goes Where
+
+| Content | Location | Examples |
+|---------|----------|---------|
+| Product code | `repo/` | Source, tests, configs, SKILL.md files |
+| Dev documentation | `wiki/` | Architecture, guides, specs, conventions |
+| Repo README | `repo/README.md` | Minimal — quick start + link to wiki |
+| Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki pages |
+| Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
+| Active task context | `wip/` | WIP files for Basecamp todos or GitHub issues |
+| Dev secrets | `protected/` | API keys, tokens, test credentials |
+
+Rule of thumb: if a `.md` file isn't built into the end product, it belongs in the wiki. If it contains secrets or ephemeral task state, it belongs outside both git trees.
+
+## WIP Directory
+
+The `wip/` directory holds work-in-progress files that AI agents create when picking up tasks from Basecamp or GitHub issues. Each file tracks research, plans, and progress for an active task.
+
+### Naming Convention
+
+`{issue-number}-{short-description}.md` — e.g., `14-basecamp-mcp-auto-refresh-oauth.md`
+
+### Lifecycle
+
+1. Agent picks up a Basecamp todo or GitHub issue
+2. Creates a WIP file with research findings and implementation plan
+3. Updates the file as work progresses
+4. File remains after completion as a record of decisions made
+
+### What belongs in WIP
+
+- Research findings and code analysis
+- Detailed implementation plans
+- Decision rationale
+- Test results and verification notes
+
+### What does NOT belong in WIP
+
+- Secrets, credentials, or tokens (use `protected/`)
+- Final documentation (use `wiki/`)
+- Code (use `repo/`)
+
+## Protected Directory
+
+The `protected/` directory stores secrets and credentials needed during development and testing. It sits outside all git trees so nothing can be accidentally committed.
+
+Examples: API keys, OAuth tokens, test credentials, `.env` files for local testing.
+
+MUST NOT be committed to any git repository. MUST NOT be copied into `repo/` or `wiki/`.
+
+## Referencing Wiki from Repo
+
+Repo files SHOULD use **relative filesystem paths** to reference wiki content:
+
+```markdown
+Full docs: ../../../wiki/Versioning.md
+```
+
+Relative paths work for Claude Code (local file reads). GitHub URLs require network access and are slower.
+
+## Wiki Conventions
+
+### Page Naming
+
+- Use **PascalCase** with hyphens: `Getting-Started.md`, `Plugin-Structure.md`
+- Match the pattern used in GitHub wiki URLs: `wiki/Page-Name`
+
+### _Sidebar.md
+
+Every wiki MUST have a `_Sidebar.md` for navigation. Group pages by topic:
+
+```markdown
+**[[Home]]**
+
+**Getting Started**
+- [[Getting-Started]]
+
+**Architecture**
+- [[Architecture]]
+- [[Plugin-Structure]]
+
+**Development**
+- [[Development]]
+- [[Versioning]]
+```
+
+### Linking
+
+- Use `[[Page-Name]]` wiki links for internal links (renders on GitHub wiki)
+- Use `[[Display Text|Page-Name]]` for custom link text
+
+### Content Guidelines
+
+- Wiki pages are the **full, detailed** version of documentation
+- Each page SHOULD be self-contained — don't assume the reader has seen other pages
+- Include examples, code blocks, and tables where they help
+- Use RFC 2119 keywords (MUST/SHOULD/MAY) for requirements
+
+### Committing Wiki Changes
+
+The wiki is a regular git repo. Commit and push like any other:
+
+```bash
+cd {project}/wiki
+git add -A && git commit -m "docs: add architecture page"
+git push origin master
+```
+
+Note: GitHub wikis typically use `master` as the default branch, not `main`.

package/skills/simpleapps/github/wiki-as-context.md

@@ -0,0 +1,162 @@
+# Wiki as Context
+
+The GitHub wiki is the **single source of truth** for how a project works. It is not an afterthought or a place to dump notes — it is the primary context that drives development.
+
+## The Problem
+
+Documentation scattered across a codebase creates friction:
+
+- `.claude/rules/` files, README.md, inline comments, and docs/ folders all compete as sources of truth
+- AI agents waste tokens reading large files to find relevant context
+- New team members don't know where to look
+- Docs rot because they live next to code and get forgotten
+
+## The Solution
+
+The wiki is the **spec**. The repo is the **implementation**.
+
+| Wiki | Repo |
+|------|------|
+| Architecture decisions | Code that implements them |
+| API specs | API code |
+| Conventions and standards | Code that follows them |
+| Onboarding guides | Nothing — wiki is self-contained |
+| Release processes | Automation scripts |
+| Full explanations | Minimal pointers back to wiki |
+
+## How It Works
+
+### 1. Wiki First
+
+When starting new work, check the wiki first. If the wiki doesn't cover it, write the wiki page before writing code. The wiki defines *what* and *why*. The code implements *how*.
+
+### 2. Repo References Wiki
+
+Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) SHOULD be **minimal** — just enough to orient, then point to the wiki for details.
+
+```markdown
+# Versioning
+
+Full docs: ../../../wiki/Versioning.md
+
+`VERSION` file = source of truth. All version fields MUST match.
+```
+
+### 3. AI Agents Read Wiki Locally
+
+Because the wiki is cloned alongside the repo (see `project-structure.md`), AI agents read wiki pages as local files. No network requests, no URL fetching — just `Read ../../../wiki/Architecture.md`.
+
+This means wiki pages are both human documentation AND machine context.
+
+### 4. Wiki Evolves with the Project
+
+The wiki is not write-once. As the codebase changes:
+
+- Update affected wiki pages in the same work session
+- Add new pages when new patterns emerge
+- Remove pages when features are deprecated
+- Keep the `_Sidebar.md` current
+
+## Three Audiences
+
+Every wiki page serves three audiences simultaneously:
+
+| Audience | What they need | How they read |
+|----------|---------------|---------------|
+| **Junior devs** | Explanations of *why*, step-by-step instructions, examples they can copy | Top to bottom, following links for context |
+| **Senior devs** | Quick reference, architecture decisions, conventions to follow | Scan for the section they need, skip the rest |
+| **AI agents** | Unambiguous specs, exact commands, clear requirements (MUST/SHOULD/MAY) | Load the full wiki into context, act on it |
+
+### Writing for All Three
+
+- **Lead with a summary** — seniors and agents get what they need fast, juniors get orientation
+- **Explain the *why* before the *how*** — juniors learn the reasoning, seniors confirm their assumptions, agents get decision context
+- **Use tables for reference data** — scannable for seniors, parseable for agents, structured for juniors
+- **Use code blocks for anything copy-pasteable** — all three audiences benefit from exact commands
+- **Use RFC 2119 keywords (MUST/SHOULD/MAY)** — removes ambiguity for everyone, especially agents
+- **Include examples** — juniors learn by example, agents use them as patterns
+
+### Keep Pages Self-Contained
+
+Each page SHOULD make sense on its own. A junior dev landing on any page SHOULD be able to understand it without reading the rest of the wiki.
+
+### Follow the Writing Style Skill
+
+All wiki content MUST follow the `simpleapps:writing-style` skill:
+
+- **RFC 2119 keywords** — MUST/SHOULD/MAY in ALL CAPS for requirements, lowercase for casual suggestions
+- **Token efficiency** — action verbs first, no filler, specific over generic, Bottom Line Up Front
+- **Developer-facing tone** — technical and concise, include file references and acceptance criteria
+- **Expand for onboarding and architecture** — juniors and future devs need the "why"
+- **Cut everywhere else** — two sentences that answer the question beat two pages that fill the context window
+
+The wiki is developer-facing documentation. It is NOT client-facing. Write for devs and AI agents, not for non-technical readers.
+
+### Link with Anchor Precision
+
+When referencing other wiki pages, MUST link directly to the relevant section using `#` anchors — not just the page.
+
+```markdown
+# Good — links to exact section
+See [[Versioning#version-bump-procedure]] for the step-by-step process.
+Check [[Architecture#three-layers]] for how marketplace, plugins, and CLI relate.
+
+# Bad — links to top of page, reader has to hunt
+See [[Versioning]] for details.
+Check [[Architecture]] for more info.
+```
+
+This matters for two reasons:
+- **Devs** jump straight to the answer instead of scrolling through a page
+- **AI agents** use anchor links as an attention signal — a `#section` reference tells the agent exactly which part of a page is relevant to the current task, reducing noise in a 20K token wiki
+
+### The 20K Token Budget
+
+The entire wiki MUST stay under **20K tokens** (~60KB of markdown). This is a hard constraint, not a guideline.
+
+Why 20K: with a 200K token context window, the full wiki never exceeds 10% of available context. This means an AI agent can load the **entire wiki** into active context at the start of a session and keep it there throughout. No selective loading, no missed context, no stale references — the agent always has the complete picture.
+
+If the wiki approaches the budget:
+- Tighten language — cut filler, use tables over prose
+- Merge overlapping pages
+- Move implementation details back to code comments where they belong
+- Archive obsolete pages (delete, don't hoard)
+
+To check the current budget:
+```bash
+wc -c {project}/wiki/*.md
+```
+
+Rough conversion: 1 token ≈ 3 bytes of markdown. So 20K tokens ≈ 60KB.
+
+### Right-Size Each Page
+
+- Too short = missing context, agent has to search elsewhere
+- Too long = wasted tokens, buried signal
+- Target: enough to act on without reading anything else
+
+## The Feedback Loop
+
+```
+Wiki defines → Code implements → Learnings update wiki → Repeat
+```
+
+When code reveals that the wiki is wrong or incomplete, update the wiki immediately. The wiki MUST reflect reality, not aspirations.
+
+## When to Update the Wiki
+
+- **New feature** — Write the wiki page first (spec), then implement
+- **Bug fix** — If the fix reveals a gap in documentation, update the wiki
+- **Architecture change** — Update Architecture page before or during the change
+- **New convention** — Add to the relevant wiki page so the team adopts it
+- **Onboarding friction** — If someone asks "where is X?", the answer should be a wiki link. If it's not, create the page.
+
+## Anti-Patterns
+
+| Don't | Do |
+|-------|-----|
+| Write long README.md files in the repo | Minimal README + wiki link |
+| Duplicate wiki content in `.claude/rules/` | Thin rules that reference wiki |
+| Leave wiki pages stale after code changes | Update wiki in the same session |
+| Use the wiki as a dumping ground for notes | Structure pages with clear purpose |
+| Write wiki pages only humans can understand | Write for both humans and AI agents |

package/skills/simpleapps/workflow/SKILL.md

@@ -34,4 +34,6 @@ The `basecamp` MCP server (bundled with this plugin) provides direct API access
 ## References
 
 - See `basecamp.md` for MCP tools, Chrome fallback, and Basecamp navigation
-- See `github.md` for GitHub issue creation and cross-linking
+- See `github.md` for Basecamp-to-GitHub cross-linking
+- See `simpleapps:github` skill for GitHub org conventions and `gh` CLI usage
+- See `simpleapps:fyxer` skill for Fyxer meeting transcript processing and Basecamp posting

package/skills/simpleapps/workflow/basecamp.md

@@ -1,6 +1,8 @@
 # Basecamp 2 Reference
 
-IMPORTANT: YOU MUST NOT create, edit, or delete anything in Basecamp — except reassigning todos via `assign_todo`.
+IMPORTANT: YOU MUST NOT create, edit, or delete anything in Basecamp without user permission.
+
+**Content format**: All write tools SHOULD use plain text with line breaks, NOT HTML. Basecamp returns HTML in responses but prefers plain text for creation.
 
 ## Setup
 
@@ -21,6 +23,10 @@ The `basecamp` MCP server is bundled with this plugin and starts automatically.
 |------|-------------|
 | `list_projects` | List projects. status: 'active', 'drafts', or 'archived' |
 | `get_project` | Get project details by project_id |
+| `create_project` | Create a new project (name, description) |
+| `update_project` | Update project name/description |
+| `archive_project` | Archive or unarchive a project (archive=False to reactivate) |
+| `delete_project` | Delete a project permanently |
 
 ### People
 | Tool | Description |
@@ -28,16 +34,29 @@ The `basecamp` MCP server is bundled with this plugin and starts automatically.
 | `list_people` | List all people on the account |
 | `get_person` | Get person details by person_id |
 | `get_me` | Get the authenticated user's profile |
+| `list_person_projects` | List projects accessible to a person |
+| `delete_person` | Remove a person from the account (admin only) |
 
 ### Todos
 | Tool | Description |
 |------|-------------|
-| `get_todo` | Get a single todo with comments (project_id, todo_id) |
+| `get_todo` | Get a single todo with comments and attachments (project_id, todo_id) |
 | `list_todos` | List todos in a project. status: 'remaining', 'completed', or 'all' |
 | `list_todos_due_since` | List todos due after a date (YYYY-MM-DD) |
 | `list_my_todos` | List all open todos assigned to the current user (paginated) |
 | `list_assigned_todos` | List open todos assigned to any person_id |
+| `create_todo` | Create a todo in a todo list (project_id, todolist_id, content, assignee_id, due_date) |
+| `update_todo` | Update a todo's content, due date, or assignee |
 | `assign_todo` | Reassign a todo to a different person_id |
+| `close_todo` | Mark a todo as completed/closed |
+| `reopen_todo` | Reopen a completed todo |
+| `delete_todo` | Delete a todo permanently |
+
+### Comments
+| Tool | Description |
+|------|-------------|
+| `create_comment` | Add a comment to a todo (plain text) |
+| `delete_comment` | Delete a comment permanently |
 
 ### Todo Lists
 | Tool | Description |
@@ -45,12 +64,18 @@ The `basecamp` MCP server is bundled with this plugin and starts automatically.
 | `list_todolists` | List active todo lists in a project |
 | `list_all_todolists` | List todo lists across all projects. status: 'active', 'completed', or 'trashed' |
 | `get_todolist` | Get all todos in a specific todo list |
+| `create_todolist` | Create a new todo list (project_id, name, description) |
+| `update_todolist` | Update a todo list's name, description, or position |
+| `delete_todolist` | Delete a todo list permanently |
 
 ### Messages
 | Tool | Description |
 |------|-------------|
-| `list_messages` | List messages in a project |
-| `get_message` | Get a message with comments |
+| `list_messages` | List messages/discussions in a project (via topics) |
+| `get_message` | Get a message with comments and attachments |
+| `create_message` | Create a new discussion (project_id, subject, content) |
+| `update_message` | Update a message's subject/content |
+| `delete_message` | Delete a message permanently |
 
 Note: Messages may not be available on all Basecamp plans.
 
@@ -59,6 +84,9 @@ Note: Messages may not be available on all Basecamp plans.
 |------|-------------|
 | `list_documents` | List documents. project_id=0 for all projects |
 | `get_document` | Get a single document (e.g., site-info) |
+| `create_document` | Create a new document (title, content) |
+| `update_document` | Update a document's title/content |
+| `delete_document` | Delete a document permanently |
 
 ### Calendar Events
 | Tool | Description |
@@ -66,26 +94,68 @@ Note: Messages may not be available on all Basecamp plans.
 | `list_calendars` | List all calendars |
 | `list_calendar_events` | List events. Filter by project_id, start_date, end_date, past |
 | `get_calendar_event` | Get a specific calendar event |
+| `create_calendar_event` | Create an event (summary, starts_at, description, all_day, ends_at, remind_at) |
+| `update_calendar_event` | Update an event's fields |
+| `delete_calendar_event` | Delete a calendar event |
 
-### Topics, Events, Attachments
+### Topics
 | Tool | Description |
 |------|-------------|
 | `list_topics` | List topics. project_id=0 for all. archived=True for archived |
-| `list_events` | Activity log since a datetime. Filter by project_id or person_id |
+| `archive_topic` | Archive a topic |
+| `activate_topic` | Reactivate an archived topic |
+
+### Attachments & Uploads
+| Tool | Description |
+|------|-------------|
 | `list_attachments` | List attachments. project_id=0 for all (paginated) |
+| `get_attachment` | Get attachment metadata and download URL (project_id, attachment_id) |
+| `download_attachment` | Download attachment to local file (project_id, attachment_id) |
 | `get_upload` | Get an upload with comments |
+| `create_upload` | Upload a local file to a project's Files section |
+| `delete_upload` | Delete an upload (move to trash) |
+
+### Activity
+| Tool | Description |
+|------|-------------|
+| `list_events` | Activity log since a datetime. Filter by project_id or person_id |
 
-### Other
+### Access Management
 | Tool | Description |
 |------|-------------|
 | `list_accesses` | List people with access to a project |
+| `grant_access` | Grant team access (comma-separated ids and/or email_addresses) |
+| `grant_client_access` | Grant client-level access (comma-separated ids and/or email_addresses) |
+| `revoke_access` | Revoke a person's project access |
+
+### Stars
+| Tool | Description |
+|------|-------------|
 | `list_stars` | List starred/favorite projects |
+| `star_project` | Star (bookmark) a project |
+| `unstar_project` | Remove star from a project |
+
+### Forwards
+| Tool | Description |
+|------|-------------|
 | `list_forwards` | List email forwards. project_id=0 for all |
 | `get_forward` | Get a specific email forward with comments |
-| `search` | Search across all projects |
+
+**Note**: The BCX API does not have a search endpoint. To find content, use `list_topics(project_id)` to browse, or `list_messages(project_id)` for messages. For cross-project browsing, use `list_topics()` (no project_id) to get recent topics across all projects.
 
 **Extracting IDs from Basecamp URLs**: A URL like `https://basecamp.com/2805226/projects/18932786/todos/514631271` gives you project_id=`18932786` and todo_id=`514631271`.
 
+## Downloading Attachments
+
+Attachments can be on todos, comments, messages, or uploads. To retrieve them:
+
+1. **Discover**: Call `get_todo` or `get_message` — attachments appear with IDs in both the top-level section and within individual comments
+2. **Inspect** (optional): Call `get_attachment(project_id, attachment_id)` to see metadata, size, content type, and download URL
+3. **Download**: Call `download_attachment(project_id, attachment_id)` — saves to `~/.simpleapps/downloads/{project_id}/`
+4. **Read**: Use the `Read` tool on the local file path to view content (works for images, PDFs, Excel, text)
+
+To browse all attachments in a project, use `list_attachments(project_id)`.
+
 ## Chrome Fallback
 
 If the MCP server is unavailable (credentials expired, server not running), use Chrome:
@@ -112,6 +182,10 @@ If the MCP server is unavailable (credentials expired, server not running), use
 
 **JSON API via Chrome**: Navigate to `/api/v1/projects/<project_id>/todos/<todo_id>.json` then use `get_page_text`. WebFetch will NOT work — Chrome carries session cookies.
 
+## Fyxer Meeting Transcripts
+
+To post Fyxer meeting recordings as Basecamp Discussions, see the `simpleapps:fyxer` skill. It handles extraction, local caching, duplicate detection, and posting via `create_message`.
+
 ## Site Info Documents
 
 Each Basecamp project SHOULD have a **site-info** text document in its Documents section. It contains site-specific details like siteId and domain name needed for GitHub issues and development work. Use `list_documents` + `get_document` to find it. If no site-info document exists, ask the user to create one.

package/skills/simpleapps/workflow/github.md

@@ -1,12 +1,16 @@
-# GitHub Issues Reference
+# Basecamp → GitHub Cross-Linking
+
+When a client request in Basecamp needs development work, create a GitHub issue and cross-link them.
 
 ## Creating Issues from Basecamp Todos
 
-Before creating an issue, gather context:
-1. Use `get_todo` (MCP) to read the Basecamp todo and summarize the client request
-2. Use `list_documents` + `get_document` (MCP) to find the project's **site-info** document for siteId and domain name. If no site-info document exists, ask the user to create one in Basecamp.
+Before creating an issue, gather context from Basecamp (see `basecamp.md` for full MCP tool reference):
+1. Use `get_todo` to read the Basecamp todo and summarize the client request
+2. Use `list_documents` + `get_document` to find the project's **site-info** document for siteId and domain name. If no site-info document exists, ask the user to create one in Basecamp.
+
+See the `simpleapps:github` skill for `gh` CLI usage and org conventions.
 
-Use `gh issue create` to create issues linked to Basecamp todos:
+Issue template for Basecamp-linked issues:
 
 ```bash
 gh issue create --repo simpleapps-com/<repo> \
@@ -28,19 +32,3 @@ gh issue create --repo simpleapps-com/<repo> \
 
 - Include the Basecamp todo URL in the GitHub issue body (under a `## Basecamp` heading)
 - After creating the issue, provide the GitHub issue URL to the user so they can add it to the Basecamp todo comments
-
-## Conventions
-
-- YOU MUST ALWAYS ask the user which GitHub repo to create the issue in — it could be the client site repo, the augur repo, or any other repo in the org
-- Issue title SHOULD be a technical description, not the client's words
-- Reference the Basecamp todo as the source of the request
-- Use labels to categorize (bug, feature, enhancement)
-- Assign to the appropriate developer
-
-## Useful Commands
-
-```bash
-gh issue list --repo simpleapps-com/<repo>           # List open issues
-gh issue view <number> --repo simpleapps-com/<repo>  # View issue details
-gh issue create --repo simpleapps-com/<repo>         # Create new issue
-```