From 92a15d3e1a1bbc172e189ce59c72c7b73b865e89 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Thu, 22 Oct 2026 15:44:03 -0400 Subject: [PATCH] rename(547): the header draws the clasped grimoire, and the README takes the standard shape AppLogo still drew the old open book with a spark, so the new mark showed only in the browser tab. It now draws the same clasped grimoire as favicon.svg, in the mark's own fixed colours. That covers the header and the sign-in, register and password pages. The README follows the house order: the logo, name and tagline, a short summary, quick start including the plugin install, the settings a reader must set, setup pitfalls, updating and backups, features grouped by what you do, troubleshooting by the error text, development, and licence. Co-Authored-By: Claude Opus 5.5 --- README.md | 121 ++++++++++++++++++++++------ frontend/src/components/AppLogo.vue | 58 +++++-------- 2 files changed, 113 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index ae5c924e..38d45cfe 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,111 @@ -# Fabled Grimoire +

+ +

-A self-hosted work system-of-record for software projects, built to be driven by Claude Code. Notes, tasks, issues, projects, milestones, rules, and stored processes — reachable from Claude via a built-in MCP endpoint and a bundled Claude Code plugin, with a clean web UI for humans. No in-app LLM; Claude is the sole assistant. +

Fabled Grimoire

-## Features +

A self-hosted system of record for the work you do with Claude Code.

-Notes, tasks and issues; projects with milestones as plans; rules that reach Claude when its work matches them or at a moment of work; lessons, snippets of prior art and a ledger of the code they account for; design systems; ideas shared across projects on the same platform; and stored processes. Semantic search feeds both Claude's recall and the plugin's context injection. A knowledge graph, sharing with users and groups, and scheduled backups round it out. See [Features](docs/features.md). +Claude records what it learned, decided and built in Grimoire, and that record reaches the next session, so a solution is recalled instead of reinvented. Notes, tasks, plans, rules, lessons and reusable code live in one place. Claude reaches them through a built-in MCP endpoint and the bundled Claude Code plugin, and people read and edit the same records in the web UI. There is no language model inside Grimoire: Claude is the only assistant. -## Quick Start +## Quick start -**Prerequisites:** Docker and Docker Compose. No GPU or local model needed — Claude is the sole assistant, reached over MCP. - -Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml) from this repo, then: +You need Docker with Compose. Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml), then: ```bash -# Optional but recommended — set a secret key -export SECRET_KEY=your-random-secret-here +SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \ + docker compose -f docker-compose.quickstart.yml up -d +``` +Open `http://localhost:5000`. The first account you register becomes the admin. + +To connect Claude, create an API key under **Settings → MCP Access**, then in Claude Code: + +``` +/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git +/plugin install grimoire@grimoire-plugin +``` + +The plugin asks for your Grimoire URL and the API key. Settings → MCP Access shows the exact commands for your instance. + +## Configuration + +Set these in the environment or a `.env` file beside the compose file: + +| Variable | Needed | What it does | +|----------|--------|--------------| +| `SECRET_KEY` | Yes | Signs sessions and seals stored credentials. Set it once and keep it | +| `BASE_URL` | Behind a proxy | The public URL, used in email links and SSO redirects | +| `SECURE_COOKIES` | Over HTTPS | `true` when Grimoire is served over HTTPS | +| `TRUST_PROXY_HEADERS` | Behind a proxy | `true` to read the client address from the proxy's headers | +| `POSTGRES_PASSWORD` | Recommended | The database password (defaults to `grimoire`) | + +Everything else (registration, email, SSO, git forge connections, retrieval tuning, backups) is in **Settings**, or listed in [Configuration](docs/configuration.md). + +## Setup pitfalls + +- **Keep your `SECRET_KEY`.** Forge tokens and the backup bucket's secret are sealed under it. If it changes, Settings asks you to enter those credentials again. +- **The embedding model downloads on first use**, into the `/data` volume. Without internet access, semantic search falls back to keyword search until the model is in place. +- **Behind a reverse proxy, turn off response buffering** for `/mcp`, because MCP responses stream. [Configuration](docs/configuration.md#behind-a-reverse-proxy) has an Nginx example. + +## Updating and backups + +```bash +docker compose -f docker-compose.quickstart.yml pull docker compose -f docker-compose.quickstart.yml up -d ``` -Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → MCP Access** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md). +Database migrations run when the app starts. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update. -> **Development:** To build from source, see [Development](docs/development.md). +Everything Grimoire stores is in the database. **Settings → Data → Scheduled backups** writes a daily backup to a folder or an S3-compatible bucket, and `python -m grimoire.restore` brings a fresh instance back from one. See [Backups](docs/backups.md). -## Documentation +## Features -| Doc | Contents | -|-----|----------| -| [Architecture](docs/architecture.md) | Stack, design decisions, data models, key services | -| [Configuration](docs/configuration.md) | Environment variables, Docker Compose, production setup, security | -| [Features](docs/features.md) | Detailed feature breakdown and keyboard shortcuts | -| [Development](docs/development.md) | Dev workflow, CI/CD, migrations, release process | -| [API Keys & MCP](docs/api-keys-and-mcp.md) | API keys and installing the Claude Code plugin | -| [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers | -| [Backups](docs/backups.md) | Scheduled backups to a folder or S3, and restoring from one | -| [Design system](docs/design-system.md) | The FabledSword house style and how Grimoire applies it | -| [API Reference](docs/api-reference.md) | All REST API endpoints | +**Working with Claude** +- Claude enters a project and gets a short primer: its goal, current plans, open tasks and areas. +- Your rules reach Claude when its work matches them, or at a moment of work such as finishing a task or pushing code. +- Before Claude writes a file or runs a command, the plugin shows it the rules, lessons and reusable code that may apply. +- Stored procedures, such as a drift audit, become Claude Code skills. -## License +**Recording the work** +- Notes in a Markdown editor, with wikilinks, tags and version history. +- Tasks, issues and time-boxed investigations, with work logs that the next session reads first. +- Plans as milestones: a design plus ordered steps. +- Lessons learned the hard way, linked to the rules they illustrate. +- Duplicate checks, so a new record that matches an existing one updates it instead. -This project is privately maintained. +**Reusing code** +- Snippets of reusable code, each with when to reach for it and where it lives in the repo. +- With a git forge connected, Grimoire tracks every function and style in your repos and shows which ones are still unaccounted for. +- Ideas shared across projects on the same platform, with each project's answer recorded. +- Design systems with tokens, inheritance and a generated stylesheet. + +**For people** +- A web UI to browse, search and edit everything, plus a graph of how notes connect. +- Sharing with users and groups, as viewer, editor or admin. +- Email and password sign-in, optional SSO through OIDC, and invite links. +- Personal export to Markdown or JSON, and admin backup and restore. + +The full list is in [Features](docs/features.md). + +## Troubleshooting + +| What you see | Why | Fix | +|--------------|-----|-----| +| `SECRET_KEY is set to the insecure default` at startup | `SECURE_COOKIES=true` while `SECRET_KEY` is still the built-in default | Set `SECRET_KEY` | +| `Can't locate revision identified by '…'` at startup | An older image is running against a database a newer one has already migrated | Run the newer image; migrations only move forward | +| The plugin's tools are missing in Claude Code | The plugin isn't installed, or Claude Code hasn't reloaded it | `/plugin` to install or update it, then `/reload-plugins` | +| Search finds only exact words | The embedding model hasn't downloaded yet | Give the app internet access once, or wait for the first download to finish | + +## Development + +```bash +cp .env.example .env # then set SECRET_KEY +docker compose up --build +``` + +[Development](docs/development.md) covers checks, migrations, the plugin and CI. [Architecture](docs/architecture.md) describes how it is built, and the [API reference](docs/api-reference.md) lists every REST endpoint. + +## Licence + +Fabled Grimoire is privately maintained. All rights reserved. diff --git a/frontend/src/components/AppLogo.vue b/frontend/src/components/AppLogo.vue index 30bff082..0a64d744 100644 --- a/frontend/src/components/AppLogo.vue +++ b/frontend/src/components/AppLogo.vue @@ -3,6 +3,8 @@ defineProps<{ size?: number }>(); - -