docs: architecture, configuration, development and features describe Scribe as it is today
Milestone 544, step 6217 (follow-up to #1778, which rewrote features.md and api-reference.md in July but left architecture.md and configuration.md alone). - architecture.md, configuration.md, development.md: rewritten against the code. They still described Ollama, chat, SSE generation, voice, project summaries, image caching, Docker secrets that the compose files don't use, a raw-SQL migration convention the migrations no longer follow, a 27-entry migration list, CalVer YY.MM.DD.N tags and the removed infra/ files. - features.md: adds what shipped since July (spikes, claims, moments, rule versions and verification, lessons, reply shapes, snippets and the shape ledger, forge integration, family canon, design systems, retrieval tuning) and corrects the Settings tabs and keyboard shortcuts (g g is the graph). - api-reference.md: adds the endpoints for snippets, lessons, design systems, family canon, platforms, shared areas, retrieval, rule versions, relations and verification, forge connections, webhooks, scheduled backups and the newer plugin hooks. - api-keys-and-mcp.md: Settings tab is "MCP Access"; a plugin install section; the tool-family table matches the tools that exist. - design-system.md: the dated "decisions in progress" changelog (April PR log, chat/journal/calendar surfaces) becomes a short present-tense section; the stored design system is named as the authority. - sso-oauth.md: the app is Scribe, not "Fabled Assistant". - README: feature summary and doc table brought current. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5.5
+30
-16
@@ -2,7 +2,7 @@
|
||||
|
||||
## API Keys
|
||||
|
||||
API keys let external tools access your Fable data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
|
||||
API keys let external tools access your Scribe data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
|
||||
|
||||
### Scopes
|
||||
|
||||
@@ -15,7 +15,7 @@ Admin-level operations (log access, user management) require a `write`-scoped ke
|
||||
|
||||
### Creating a Key
|
||||
|
||||
1. Go to **Settings → API Keys**
|
||||
1. Go to **Settings → MCP Access**
|
||||
2. Enter a name (e.g. "Claude MCP", "Home Server")
|
||||
3. Choose scope
|
||||
4. Click **Generate Key**
|
||||
@@ -26,7 +26,7 @@ config (see **Scribe MCP Server** below).
|
||||
|
||||
### Revoking a Key
|
||||
|
||||
Click **Revoke** next to the key in the API Keys table and confirm. Revoked keys are deleted immediately.
|
||||
Click **Revoke** next to the key in the keys table and confirm. Revoked keys are deleted immediately.
|
||||
|
||||
---
|
||||
|
||||
@@ -41,14 +41,25 @@ client straight to the URL with a Bearer token.
|
||||
|
||||
### Authentication
|
||||
|
||||
Authenticate with an API key generated from **Settings → API Keys** (see above),
|
||||
Authenticate with an API key generated from **Settings → MCP Access** (see above),
|
||||
sent as `Authorization: Bearer fmcp_<key>`. A `read`-scoped key may call only the
|
||||
read tools (`get_*`, `list_*`, `search`, `enter_project`, `retrieval_telemetry`);
|
||||
any write/delete tool is rejected with `403`. The allow-list is explicit rather
|
||||
than derived from the name — see `_READ_ONLY_TOOLS`, which is why the two reads
|
||||
without a read-shaped name are spelled out here. A `write`-scoped key may call everything.
|
||||
|
||||
### Claude Code (Project-scoped)
|
||||
### Claude Code: the plugin (recommended)
|
||||
|
||||
The plugin connects the MCP server and adds the hooks and skills that put Scribe's records in front of Claude as it works. Install it from this repo:
|
||||
|
||||
```
|
||||
/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledScribe.git
|
||||
/plugin install scribe@scribe-plugin
|
||||
```
|
||||
|
||||
It asks for your Scribe base URL, an API key (kept in your OS keychain) and, optionally, a project id. Settings → MCP Access shows the exact command for your instance. [`plugin/README.md`](../plugin/README.md) describes each hook.
|
||||
|
||||
### Claude Code without the plugin
|
||||
|
||||
Add a `.mcp.json` at the project root. The server `type` is `http` and the URL is
|
||||
your instance's `/mcp` endpoint:
|
||||
@@ -78,21 +89,24 @@ specific project at a dev instance or an admin key.
|
||||
|
||||
### Available Tools
|
||||
|
||||
The tool surface is large (~70 tools) and evolves with the app, so the live
|
||||
registration in **`src/scribe/mcp/tools/`** is the source of truth rather than a
|
||||
table here. The tools are grouped by family:
|
||||
There are well over a hundred tools and they change with the app, so the
|
||||
registration in **`src/scribe/mcp/tools/`** is the reference. By family:
|
||||
|
||||
| Family | Examples | Purpose |
|
||||
|--------|----------|---------|
|
||||
| Notes | `create_note`, `get_note`, `update_note`, `delete_note`, `list_notes` | Free-form knowledge |
|
||||
| Tasks | `create_task`, `update_task`, `add_task_log`, `start_planning` | Actionable work + plans |
|
||||
| Projects / Milestones | `enter_project`, `get_project`, `create_milestone`, … | Containers and outcomes |
|
||||
| Search / Recall | `search`, `get_recent`, `list_tags`, `retrieval_telemetry` | Semantic + structured recall, and the readout its thresholds are tuned from |
|
||||
| Systems | `create_system`, `list_systems`, `list_system_records` | Reusable per-project subsystems/areas |
|
||||
| Rulebooks | `list_rules`, `create_rule`, `create_project_rule`, `relate_rules`, … | Engineering/workflow rules |
|
||||
| Processes | `list_processes`, `get_process`, `create_process` | Saved prompts/workflows |
|
||||
| Notes | `create_note`, `get_note`, `update_note`, `create_records` | Knowledge, and several records that cite each other in one call |
|
||||
| Tasks | `create_task`, `update_task`, `add_task_log` | Work, issues and spikes, and their logs |
|
||||
| Projects / Milestones | `enter_project`, `start_planning`, `get_milestone` | Projects and their plans |
|
||||
| Search / Recall | `search`, `what_might_apply`, `get_recent` | Recall by meaning, and the rules that may apply to an act |
|
||||
| Systems | `create_system`, `list_system_records`, `map_system_to_canonical` | A project's areas |
|
||||
| Rules | `create_rule`, `create_project_rule`, `relate_rules`, `rule_history`, `list_moments` | Rules, preferences, their relations and moments |
|
||||
| Lessons | `create_lesson`, `judge_lesson_link` | Lessons and the rules they instance |
|
||||
| Snippets / Shapes | `create_snippet`, `verify_snippet`, `classify_shapes`, `list_shapes` | Prior art and the shape ledger |
|
||||
| Design systems | `resolve_design_system`, `get_design_system_stylesheet` | Tokens and guidance for UI work |
|
||||
| Family canon | `list_family_ideas`, `assess_family_adoption` | Ideas shared across projects |
|
||||
| Processes | `list_processes`, `get_process`, `create_process` | Stored procedures |
|
||||
| Retrieval | `retrieval_telemetry`, `tune_retrieval` | What was surfaced, and the thresholds |
|
||||
| Trash | `list_trash`, `restore`, `purge_trash` | Recoverable deletes |
|
||||
| Admin | `get_app_logs` (write/admin key) | Diagnostics |
|
||||
|
||||
Server-level usage guidance — when to reach for each entity, the
|
||||
recall-before-acting reflex, and the rulebook conventions — is delivered to the
|
||||
|
||||
Reference in New Issue
Block a user