sync for release 0.9.0

.editorconfig

@@ -5,16 +5,18 @@ charset = utf-8
 end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
+indent_style = space
+tab_width = 8
 
 [*.py]
 indent_style = space
 indent_size = 4
-tab_width = 4
+tab_width = 8
 
 [*.{js,ts,jsx,tsx,json,css,scss,html,md}]
 indent_style = space
 indent_size = 2
-tab_width = 2
+tab_width = 8
 
 [Makefile]
 indent_style = tab

.github/copilot-instructions.md

@@ -1,156 +1,22 @@
 # Copilot Instructions
 
-## Repository overview
+This file is intentionally concise to reduce token overhead.
 
-- AugmentedQuill is a web-based GUI for AI-assisted prose writing, with a FastAPI backend and a React + TypeScript SPA frontend (Vite).
-- Backend lives in src/augmentedquill/, frontend in src/frontend/, tests in tests/.
-- Python 3.12+ required (CI uses 3.12). Node.js 24+ required (CI uses 24).
-- The backend serves the built frontend from static/dist; frontend build output must be present for production-like runs.
+## Canonical policy source
 
-## High-level structure and key files
+- The canonical, comprehensive agent policy for this repository is `AGENTS.md` at the repository root.
+- Apply `AGENTS.md` as the source of truth for architecture boundaries, style, testing, migration rules, and done criteria.
 
-- Backend entrypoint: src/augmentedquill/main.py (FastAPI app factory, CLI entrypoint augmentedquill).
-- Backend config utilities: src/augmentedquill/core/config.py (config paths and env interpolation).
-- API layer: src/augmentedquill/api/v1/; services: src/augmentedquill/services/.
-- Frontend entrypoints: src/frontend/index.tsx and src/frontend/App.tsx.
-- Frontend API layer: src/frontend/services/api.ts and src/frontend/services/apiClients/.
-- Build/lint/test config:
-  - pyproject.toml (pytest, ruff, black, packaging).
-  - src/frontend/package.json (npm scripts).
-  - src/frontend/eslint.config.cjs, src/frontend/vite.config.ts, src/frontend/vitest.config.ts.
-  - .pre-commit-config.yaml (ruff, black, prettier, eslint).
-  - .github/workflows/code-quality.yml (CI checks).
+## Always-enforced highlights
 
-## Runtime configuration and data
+- Keep all application LLM instructions separated from code and stored in `resources/config/instructions.json`.
+- Project/story file format changes must be backward compatible or include explicit schema/version bumps with automatic chainable migrations.
+- Prioritize maintainable, compact code with strict separation of concerns and minimal duplication.
+- Code must be professional and production-quality; avoid shortcuts and temporary hacks.
 
-- Config files are read from resources/config/ (machine.json, story.json). Examples in resources/config/examples/.
-- JSON schema contracts live in resources/schemas/.
-- Runtime data and logs are stored under data/projects/ and data/logs/.
-- Environment overrides: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL, OPENAI_TIMEOUT_S.
+## Type discipline (Python + TypeScript)
 
-## Validated commands (run in this repo)
-
-Backend setup (Python 3.12.3, venv):
-
-- Always activate the venv before running any Python commands:
-  - source venv/bin/activate
-- python -m pip install -e ".[dev]"
-
-Backend lint and tests (with venv active):
-
-- ruff check .
-- black --check .
-- python -m pytest
-
-Frontend setup (Node 18+ expected; npm install required before any frontend script):
-
-- cd src/frontend && npm install
-  - Note: npm reports 13 vulnerabilities (1 moderate, 12 high). This does not fail npm install or CI.
-
-Frontend lint, tests, build:
-
-- cd src/frontend && npm run lint
-- cd src/frontend && npm run test
-- cd src/frontend && npm run build
-  - Build outputs to static/dist and is required for production-like runs.
-
-## How to run
-
-Production-like (serves built frontend):
-
-- cd src/frontend && npm run build
-- augmentedquill --host 127.0.0.1 --port 8000
-
-Dev mode (hot reload + proxy):
-
-- Terminal 1: augmentedquill --reload --host 127.0.0.1 --port 28000
-- Terminal 2: cd src/frontend && npm run dev
-- Vite dev server runs on http://127.0.0.1:28001 and proxies /api and /static to 28000.
-
-## Required hygiene for new or modified files
-
-- All .py/.ts/.tsx/.js files must include a GPL header and a Purpose line.
-- Use python tools/enforce_code_hygiene.py . to normalize headers (this can modify files).
-- Use python tools/check_copyright.py . to validate headers (fails if missing).
-
-## CI and pre-commit parity
-
-CI runs in .github/workflows/code-quality.yml:
-
-- Backend: ruff check ., black --check, pytest.
-- Frontend: npm run lint, npx prettier --check ., npm run test, npm run build.
-  Pre-commit mirrors these via .pre-commit-config.yaml.
-
-## Root inventory (important files and directories)
-
-Files at repo root:
-
-- CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, README.md, SECURITY.md, pyproject.toml, tools.json, .pre-commit-config.yaml
-  Directories at repo root:
-- src/, tests/, tools/, docs/, resources/, static/, data/, .github/, AugmentedQuill.egg-info/
-
-Top-level directories (one level down):
-
-- src/augmentedquill/ (backend app)
-- src/frontend/ (frontend app)
-- tests/unit/ (backend tests)
-- tools/ (repo scripts)
-- resources/config/ and resources/schemas/ (config + schemas)
-- static/ (images + built frontend output)
-- data/ (local runtime data)
-
-## Key README points (summary)
-
-- Python 3.11+ and Node 18+ are required.
-- Build frontend before running the app.
-- Dev workflow: backend reload + Vite dev server.
-- Config uses JSON with env overrides; samples in resources/config/examples/.
-
-## Guidance
-
-- Prefer editing backend logic in services/ and keep API routes thin.
-- Prefer frontend changes inside features/<domain>/ and keep API calls in services/.
-- Trust these instructions and only search the repo if something is missing or contradicts these notes.
-
-## Test Data Safety (Mandatory)
-
-- Never read from or write to real user runtime files under `data/config/`, `data/projects/`, or `data/logs/` when running tests.
-- For all automated tests, force the app to use a temporary user data root by setting `AUGQ_USER_DATA_DIR` to a temp directory (for example under `/tmp`).
-- Tests and AI-generated test code must isolate runtime paths via environment variables before importing app modules so default config constants resolve into temp paths.
-- When tests need projects/registry overrides, use temp values for `AUGQ_PROJECTS_ROOT` and `AUGQ_PROJECTS_REGISTRY` inside that same temp root.
-
-## Branching and Release Policy
-
-The repository uses the following branch layout by default:
-
-- `main` — stable, reflects the last tagged release. Protected and only updated via PRs that have passed CI and reviews.
-- `develop` — integration branch for active development. Feature branches should branch from and be merged into `develop`.
-
-Release and hotfix branches follow `release/vX.Y` and `hotfix/vX.Y.Z` naming; tags should use semantic versions like `v1.2.3`.
-
-When preparing a new release, create `release/vX.Y` from `develop`, finish testing, then merge into `main` and tag. Merge the release branch back into `develop` afterwards.
-
-## Chat Tools (LLM Function Calling)
-
-To add a new chat tool:
-
-1. Define a Pydantic model for parameters in the appropriate tool file (e.g., `src/augmentedquill/services/chat/chat_tools/project_tools.py`)
-2. Decorate an async function with `@chat_tool(description="...")`
-3. Implement: `async def tool_name(params: ParamsModel, payload: dict, mutations: dict) -> dict`
-4. Return a dictionary (auto-wrapped as tool message)
-
-Example:
-
-```python
-from pydantic import BaseModel, Field
-from augmentedquill.services.chat.chat_tool_decorator import chat_tool
-
-class MyParams(BaseModel):
-    name: str = Field(..., description="Description")
-
-@chat_tool(description="Does something")
-async def my_tool(params: MyParams, payload: dict, mutations: dict):
-    return {"result": "value"}
-```
-
-Tool files: `src/augmentedquill/services/chat/chat_tools/{project,story,chapter,sourcebook,image,order}_tools.py`
+- All new/modified Python and TypeScript code must be typed.
+- Shared/library helpers should use reasonably wide reusable types where safety is preserved.
+- Application/domain functions should use the strictest minimal types possible to encode invariants.
+- Convert from wider boundary types to stricter internal types at module boundaries.

.github/workflows/code-quality.yml

@@ -31,7 +31,7 @@ jobs:
       run: pytest
 
     - name: Run pip-audit
-      run: pip-audit --ignore-vuln CVE-2026-4539
+      run: pip-audit --ignore-vuln CVE-2026-4539 --ignore-vuln CVE-2026-3219
 
   frontend-checks:
     runs-on: ubuntu-latest
@@ -46,11 +46,19 @@ jobs:
     - name: Install dependencies
       run: |
         cd src/frontend
-        npm ci
+        npm ci --legacy-peer-deps
     - name: Run ESLint
       run: |
         cd src/frontend
         npm run lint
+    - name: Run TypeScript Check
+      run: |
+        cd src/frontend
+        npm run typecheck
+    - name: Check generated API types are up-to-date
+      run: |
+        cd src/frontend
+        npm run check:generated-types
     - name: Run Prettier
       run: |
         cd src/frontend

.github/workflows/codeql-analysis.yml

@@ -36,3 +36,5 @@ jobs:
 
       - name: Perform CodeQL analysis
         uses: github/codeql-action/analyze@v3
+        with:
+          skip-queries: true

.vscode/launch.json

@@ -9,7 +9,7 @@
       "args": ["--host", "127.0.0.1", "--port", "28000", "--reload", "--llm-dump"],
       "console": "integratedTerminal",
       "justMyCode": true,
-      "preLaunchTask": "backend: clear-llm-log",
+      "preLaunchTask": "backend: prepare",
       "env": {
         "AUGQ_LLM_DUMP_LEVEL": "normal"
       }
@@ -18,7 +18,7 @@
       "name": "Frontend (Vite 28001)",
       "type": "node-terminal",
       "request": "launch",
-      "preLaunchTask": "frontend: install",
+      "preLaunchTask": "frontend: prepare",
       "command": "npm run dev -- --port 28001 --strictPort",
       "cwd": "${workspaceFolder}/src/frontend",
       "env": {

.vscode/settings.json

@@ -1,7 +1,6 @@
 {
-  "python-envs.pythonProjects": [],
   "python.terminal.activateEnvironment": true,
-  "python.defaultInterpreterPath": "./venv/bin/python",
+  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
   "python.testing.pytestArgs": ["tests"],
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true

.vscode/tasks.json

@@ -5,7 +5,7 @@
       "label": "frontend: install",
       "type": "shell",
       "command": "npm",
-      "args": ["install"],
+      "args": ["install", "--legacy-peer-deps"],
       "options": {
         "cwd": "${workspaceFolder}/src/frontend"
       },
@@ -14,6 +14,18 @@
         "reveal": "silent"
       }
     },
+    {
+      "label": "frontend: generate-types",
+      "type": "shell",
+      "command": "npm",
+      "args": ["run", "generate:types"],
+      "options": {
+        "cwd": "${workspaceFolder}/src/frontend"
+      },
+      "presentation": {
+        "reveal": "silent"
+      }
+    },
     {
       "label": "backend: clear-llm-log",
       "type": "shell",
@@ -22,6 +34,25 @@
         "reveal": "silent",
         "close": true
       }
+    },
+    {
+      "label": "backend: export-openapi",
+      "type": "shell",
+      "command": "${workspaceFolder}/venv/bin/python",
+      "args": ["tools/export_openapi.py"],
+      "presentation": {
+        "reveal": "silent"
+      }
+    },
+    {
+      "label": "backend: prepare",
+      "dependsOn": ["backend: clear-llm-log", "backend: export-openapi"],
+      "dependsOrder": "sequence"
+    },
+    {
+      "label": "frontend: prepare",
+      "dependsOn": ["frontend: install", "frontend: generate-types"],
+      "dependsOrder": "sequence"
     }
   ]
 }