FabledScribe/docs/features.md

# Features

Scribe is a self-hosted work system-of-record for software projects, built to be
driven by Claude Code. There is **no in-app LLM** — Claude is the sole assistant,
reaching Scribe through a built-in MCP endpoint and a bundled Claude Code plugin. The
web UI is a clean surface for humans to read and edit the same data.

## Notes

Write in Markdown with a live-preview editor (Tiptap/ProseMirror). Headings, bold,
italic, lists, code blocks, and task checklists render inline. A slash-command menu
(`/`) inserts common blocks.

- **Wikilinks** — Link notes with `[[Title]]` or `[[Title|Display Text]]`. Clicking
  navigates to (or auto-creates) the referenced note; the editor suggests existing
  titles while you type `[[`. Backlinks appear in the note viewer sidebar.
- **Tags** — First-class `ARRAY[text]` column with autocomplete. Hierarchical tags
  (`area/backend`) supported — filtering by `area` matches all `area/*` children.
- **Version history** — Every body edit snapshots a version (up to 20 per note).
  Browse, diff, and restore from the editor's History panel.
- **Draft recovery** — In-progress edits persist across page loads and are restored
  when you reopen a note.
- **Convert freely** — Turn a note into a task (sets `status=todo`) or back again.

## Tasks and Issues

Tasks carry status (`todo` → `in_progress` → `done`/`cancelled`), priority
(`none`/`low`/`medium`/`high`), due date, milestone assignment, and a parent task
(sub-tasks). Notes and tasks share one model — a task is a note with a status.

- **Work logs** — Append timestamped progress entries (with optional duration) to a
  task without rewriting its body; shown chronologically in the task view.
- **Issues** — A task whose `kind` is corrective: a problem you fixed or are fixing,
  with symptom → root cause → fix in the body. An issue can link the task it arose
  from and the System(s) it touches.
- **Recurring tasks** — An interval or calendar recurrence rule spawns the next
  occurrence when a task is completed (a background job drains due spawns).
- **Sub-tasks** — Any task can have children via `parent_id`; the viewer shows them
  inline.

## Projects and Milestones

- **Projects** — Group related notes and tasks. Title, description, goal, status
  (`active`/`paused`/`completed`/`archived`), and a colour.
- **Milestones** — Ordered stages within a project. A milestone is also the home of a
  **plan** — its body holds the design (Goal/Approach/Verification) and its child
  tasks are the steps. Completion percentage is shown on the project page.
- **Kanban view** — `/projects/:id` groups tasks by milestone in a column layout with
  status-advance buttons on the cards.

## Systems

A **System** is a per-project, reusable, self-describing subsystem or area (e.g.
"auth", "billing"). Associate any note, task, or issue with a System so research,
build-work, and fixes for the same area line up and recurring problem-spots surface.

## Rules and Rulebooks

Scribe stores the operator's engineering and workflow **rules** so Claude follows them
across sessions.

- **Rulebooks → topics → rules** — Rules are grouped by topic inside a rulebook.
- **Always-on rules** — A rulebook can be flagged always-on; its rules load at the
  start of every session through the plugin's push channel.
- **Per-project scope** — A project subscribes to rulebooks, and can add
  project-scoped rules or suppress individual inherited rules/topics.

## Stored Processes

Reusable saved prompts (a note with `note_type=process`) — e.g. a drift-audit or a
DRY pass. The bundled plugin syncs each Process into a local Claude Code skill stub
(`/scribe:sync`) that auto-surfaces by relevance and fetches the live procedure on
demand.

## Search and Knowledge Injection

- **Semantic search** — pgvector-backed similarity search over notes and tasks
  (in-process `fastembed` embeddings; no external model).
- **Proactive knowledge-injection** — the plugin's `UserPromptSubmit` hook surfaces a
  short, high-confidence menu of maybe-relevant note *titles* into Claude's context
  each turn; Claude pulls a full body only when it judges it relevant. Gated so it
  stays quiet on most turns and never repeats within a session.

## Knowledge Graph

`/graph` renders notes, tasks, and tags as a D3 force-directed graph. Tag nodes
cluster notes that share tags; invisible project hubs attract project members. Physics
controls (repulsion, link distance/strength, hub pull, gravity); click a node to peek,
click a tag to filter.

## Claude via MCP and the plugin

The whole store is reachable by Claude through a built-in **MCP endpoint at `/mcp`**
(Bearer-auth with an API key). The **Scribe Claude Code plugin** (shipped in this
repo) wires it up:

- a `SessionStart` hook that injects the operator's always-on rules + active-project
  context so Scribe surfaces without being asked (fail-open if Scribe is unreachable);
- universal process-skills — writing-plans, systematic-debugging, verification,
  brainstorming — that route their output into Scribe;
- your saved Processes auto-surfaced as skills.

See [API Keys & MCP](api-keys-and-mcp.md).

## Sharing and Collaboration

- **Share** — Share any project, note, or task with users or groups at
  `viewer`/`editor`/`admin` levels from the viewer/project toolbar.
- **Groups** — Admins create platform-wide groups and assign `member`/`owner` roles;
  share a resource with a group in one action.
- **Shared with me** — `/shared` lists incoming shares with permission badges.
- **Notifications** — An in-app bell (unread count, polled) fires when a project or
  note is shared with you or you're added to a group.

Every read and mutation is scoped by owner + direct shares + group shares.

## Data Export and Backup

- **Personal export** — download all your notes/tasks as a Markdown ZIP (YAML
  frontmatter) or a JSON array.
- **Admin backup** — full application backup/restore (format v4) with ID remapping on
  restore for cross-instance migration.

## Progressive Web App

Installable as a desktop or mobile app; a service worker caches the shell.

## Authentication

Native email + password, plus optional **OIDC** sign-in (Authentik, Keycloak, etc.)
that links to a matching local account. Invite links, a registration toggle, password
reset, and session invalidation are included. See [SSO / OAuth](sso-oauth.md).

## Settings

| Tab | Contents |
|-----|----------|
| General | Instance preferences (key/value) |
| Account | Email change, password change, session invalidation |
| Profile | Per-user profile fields |
| Integrations | SearXNG status |
| Data | Personal export; backup / restore (admin) |
| API Keys | Create/revoke `fmcp_` keys for the MCP endpoint |
| Config (admin) | Base URL, SMTP, DB-maintenance schedule |
| Users (admin) | User list, invite links, registration toggle |
| Logs (admin) | Error, audit, and usage logs with search |
| Groups (admin) | Create/manage groups and membership |

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `g` + `h` | Home (dashboard) |
| `g` + `n` | Notes |
| `g` + `t` | Knowledge (tasks) |
| `g` + `p` | Projects |
| `g` + `r` | Rulebooks |
| `g` (bare) | Graph |
| `g` + `x` | Trash |
| `n` | New note |
| `t` | New task |
| `/` | Focus search |
| `?` | Show shortcuts panel |
| `j` / `k` | Navigate list items |
| `Enter` | Open selected item |
| `e` | Edit current item |
| `Esc` | Close panel / blur / go home (progressive) |
| `Ctrl+S` | Save in editor |