docs: restructure documentation into docs/ directory, slim README, add project .mcp.json

- README.md: reduced to overview + quick start + links to docs/ - docs/architecture.md: stack, design decisions, data models, key services - docs/configuration.md: all env vars, docker-compose setup, production + security - docs/development.md: dev workflow, CI/CD, migrations, release process - docs/features.md: detailed feature breakdown + keyboard shortcuts - docs/api-keys-and-mcp.md: API key management + Fable MCP install guide - docs/sso-oauth.md: OAuth/OIDC setup (replaces docs/oauth-setup.md) - docs/changelog.md: development history from summary.md - Remove summary.md (content distributed across docs/) - Remove docs/oauth-setup.md (superseded by docs/sso-oauth.md) - .gitignore: add .mcp.json Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-24 21:03:15 -04:00
parent 553c38200a
commit 47e248d9ac
11 changed files with 980 additions and 1544 deletions
@@ -0,0 +1,140 @@
+# Development
+
+## Workflow
+
+All development is Docker-based. Do not install Python or Node dependencies locally.
+
+```bash
+# Start the full stack (app + PostgreSQL + Ollama)
+docker compose up --build
+
+# Rebuild after backend changes (frontend changes require rebuild too)
+docker compose up --build app
+
+# Reset everything (wipes database)
+docker compose down -v && docker compose up --build
+
+# Run checks (lint, format, typecheck, tests)
+make check
+
+# Individual checks
+make lint        # ruff check src/
+make fmt         # ruff format src/
+make typecheck   # vue-tsc --noEmit
+make test        # pytest tests/
+```
+
+## Frontend Hot Reload
+
+The Docker setup does not include Vite's hot-reload dev server. After frontend changes, rebuild the image. For faster iteration during active frontend work, you can run Vite locally:
+
+```bash
+cd frontend
+npm install
+npm run dev   # Vite dev server at http://localhost:5173
+```
+
+Point the Vite dev server at the backend by setting `VITE_API_BASE_URL=http://localhost:5000` (or configure `vite.config.ts` proxy).
+
+## Database Migrations
+
+Alembic migrations run automatically on container startup (`alembic upgrade head` in the `CMD`).
+
+To create a new migration:
+```bash
+# Inside the running app container
+docker compose exec app alembic revision -m "description_of_change"
+# Edit the generated file in alembic/versions/
+```
+
+Migration conventions:
+- Use raw SQL with `IF NOT EXISTS` guards for idempotency
+- Use `DO $$ BEGIN CREATE TYPE … EXCEPTION WHEN duplicate_object THEN NULL; END $$` for enum types
+- Number migrations sequentially (e.g. `0027_add_something.py`)
+- Always provide both `upgrade()` and `downgrade()`
+
+## CI/CD
+
+### Pipeline
+
+CI runs on Forgejo Actions with a custom runner base image (`py3.12-node22`):
+
+| Trigger | Jobs | Docker tags pushed |
+|---------|------|--------------------|
+| Push to `dev` | typecheck + lint + test → build | `:dev`, `:<sha>` |
+| Tag `v*` on `main` | typecheck + lint + test → build | `:latest`, `:<version>`, `:<sha>` |
+| Push to `main` | typecheck + lint + test | (no build) |
+
+### Release Process
+
+1. Work on `dev` branch — CI validates on every push
+2. When ready, open a PR from `dev` → `main` in Forgejo
+3. Merge the PR
+4. Create a release via the Forgejo UI on `main` with a `v*` tag (e.g. `v26.03.23.1` — CalVer: `YY.MM.DD.N`)
+5. The tag push triggers CI → build job pushes `:latest` + `:<version>` Docker images
+6. After merging to main, sync dev back:
+   ```bash
+   git checkout dev && git merge main && git push origin dev
+   ```
+
+### Custom Runner
+
+Runner base image: `infra/Dockerfile.runner-base` (Ubuntu 24.04 + Python 3.12 + Node 22 LTS).
+Runner config: `infra/act-runner-config.yml` (label: `py3.12-node22`).
+Runner compose: `infra/runner-compose.yml`.
+
+To activate a new runner registration:
+1. Copy `infra/act-runner-config.yml` → `/nfs/data/fabledsword/act_runner/config.yml`
+2. Delete `/data/.runner` in the runner container
+3. Restart the stack
+
+### Docker Registry
+
+Images pushed to: `git.fabledsword.com/bvandeusen/fabledassistant`
+Cache tag: `:cache` (reduces build time ~80%)
+
+Required secrets (repo → Settings → Secrets → Actions):
+- `REGISTRY_USER` — Forgejo username
+- `REGISTRY_TOKEN` — Forgejo PAT with `write:packages` scope
+
+## Project Conventions
+
+### Backend
+
+- Services: `async with async_session() as session:` — import from `fabledassistant.models`
+- No `fabledassistant.database` module
+- Blueprint per resource: `routes/notes.py`, `routes/tasks.py`, etc.
+- All business logic in `services/`; routes are thin wrappers
+- Permission checks via `services/access.py` — never inline ownership checks in routes
+
+### Frontend
+
+- API calls via `frontend/src/api/client.ts` typed helpers (`apiGet`, `apiPost`, `apiPatch`, `apiDelete`)
+- Pinia stores for shared state; local `ref()` for component-only state
+- Composables in `composables/` for reusable behaviour (autosave, keyboard nav, tag suggestions, …)
+- Views are page-level components in `views/`; reusable UI in `components/`
+
+### Commit Style
+
+```
+type(scope): short description
+
+Longer body if needed.
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+Scopes: feature area (e.g. `chat`, `briefing`, `fable-mcp`, `notes`)
+
+## Testing
+
+```bash
+# Run all tests
+make test
+
+# Run specific test file
+docker compose exec app /opt/venv/bin/pytest tests/test_auth.py -v
+```
+
+Tests are in `tests/`. They run against a real PostgreSQL instance in CI (not mocked). Keep tests integration-style where possible — mock failures have historically masked real migration bugs.