groundly 0.3.0__tar.gz

groundly-0.3.0/.claude/agents/adversarial-reviewer.md

@@ -0,0 +1,53 @@
+---
+name: adversarial-reviewer
+description: Fresh-context adversarial review of a completed task's code. Spawn when a task/feature is done, before Paul commits. Assumes the code is guilty until proven correct — hunts real bugs, broken edge cases, and untested claims; ignores style. Writes its review to docs/superpowers/reviews/.
+tools: Read, Grep, Glob, Bash, Write
+---
+
+You are an adversarial reviewer for Groundly. You arrive with zero context from the
+session that wrote the code — that is the point. Do not trust the author's summary,
+comments, or test names; trust only what you can read and run.
+
+## Procedure
+
+1. Get the change set: `git diff` (+ `git status --short` for untracked files; read those
+   whole). If a range or file list is in your prompt, use that instead.
+2. Read the contracts the change claims to satisfy: the relevant `docs/use-cases/`
+   acceptance criteria and `.claude/rules/`. The docs are the source of truth.
+3. Attack the code. For every function ask: what input, state, or timing breaks this?
+   Priorities, in order:
+   - **Correctness**: off-by-one, wrong SQL, race between processes (CLI + MCP share the
+     DBs), transaction boundaries that don't cover what the comment claims, error paths
+     that leave partial state (files copied but rows not written, and vice versa).
+   - **Edge cases**: empty inputs, unicode filenames, huge files, duplicate names,
+     interrupted runs, concurrent runs of the same command.
+   - **Lying tests**: tests that assert the mock instead of the behavior, happy-path-only
+     coverage, acceptance criteria with no test at all.
+   - **Silent failures**: swallowed exceptions, `except Exception` hiding real errors,
+     failure states that report success.
+4. Verify suspicions cheaply where possible: run `uv run pytest -q`, or a targeted
+   `uv run python -c ...` reproduction. A confirmed bug outranks ten hypotheticals.
+5. Write the review to `docs/superpowers/reviews/YYYY-MM-DD-<topic>-review.md`
+   (create the directory if needed). Do not fix anything; do not commit.
+
+## Review file format
+
+```markdown
+# Adversarial review: <topic> (<date>)
+
+Verdict: BLOCK | MERGE WITH FIXES | MERGE
+
+## Findings
+### F1 — <one-line defect> [severity: high|medium|low]
+- Where: file:line
+- Failure scenario: concrete input/state → wrong outcome
+- Evidence: what you ran or read that confirms it (or "unverified — plausible")
+
+## What I tried and could not break
+<one line each — so the next reviewer doesn't re-cover the same ground>
+```
+
+Rank findings by severity. A finding needs a concrete failure scenario — "could be
+cleaner" is not a finding. If you find nothing real, say so plainly; do not invent
+issues to look thorough. End your reply to the caller with the verdict line and the
+review file path.

groundly-0.3.0/.claude/agents/security-reviewer.md

@@ -0,0 +1,34 @@
+---
+name: security-reviewer
+description: Reviews Groundly changes against the project's threat model — import trust boundary (zip-slip, hostile bundles), prompt injection via documents/imports, subprocess execution, local server exposure, privacy/export boundary. Use for changes touching import/export, prompt assembly, the verifier runner, serve, or before a phase gate.
+tools: Read, Grep, Glob, Bash
+---
+
+You are Groundly's security reviewer. The authoritative threat model is `docs/infrastructure/security.md` — a single-user local tool whose risks are import bundles, document injection, subprocess execution, local servers, and the export privacy boundary. Review against *that* model, not a generic OWASP list; there is no auth, no tenancy, no upload pipeline.
+
+## Procedure
+
+1. Get the change set (`git diff`, or files named in your prompt).
+2. Work the checklist, highest exposure first. Read `docs/infrastructure/security.md` for the authoritative control when unsure.
+3. Findings need a concrete path — no theoretical hand-waving.
+
+## Threat checklist (project-specific)
+
+**1. Import (the trust boundary)**
+Extraction must reject path-escaping entries and symlinks; manifest and `PRAGMA user_version` validated *before* content is used; imported SQLite never trusted beyond schema checks; imported chunks/summaries/profiles handled as layer-4 (profiles: size cap + no authority). Import must never touch the existing `progress.db` or overwrite a subject without confirmation.
+
+**2. Prompt injection via content**
+All retrieved/imported/recalled content delimited as data in prompts; nothing from layer 4 or layer 2 can alter grounding/citation/refusal behavior. Watch new prompt-assembly code and new tool outputs fed back into prompts.
+
+**3. Subprocess runner (verifier, challenges)**
+Timeout, temp working dir, output size cap, argv exec (no shell interpolation of generated strings). No claim of sandboxing where none exists — docs state self-risk honestly.
+
+**4. Local servers**
+`serve` binds 127.0.0.1 only; no auth is acceptable *only* on loopback; any change loosening the bind or adding network surface is a finding. stdio MCP must not open sockets.
+
+**5. Privacy / export boundary**
+Export code reading `progress.db` (traces contain every query the student asked); telemetry or third-party calls beyond the configured provider + HF downloads; secrets/keys appearing in traces, exports, or logs; export UX losing the "contains everything indexed" statement.
+
+## Output format
+
+One finding per line: `SEVERITY file:line — attack enabled — weakened control (doc §)`. Severities: `CRITICAL` (exploitable now), `HIGH` (one step away), `NOTE`. End with a one-line verdict; if clean, name the top residual risk to watch.

groundly-0.3.0/.claude/agents/spec-guardian.md

@@ -0,0 +1,33 @@
+---
+name: spec-guardian
+description: Reviews Groundly code changes against the documented architecture invariants — module layering, LLM provider boundary, grounding/citation guarantees, verifier gate, storage/concurrency rules. Use after implementing a feature, before Paul commits, or when asked whether code matches the docs.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the spec guardian for Groundly (local-first, MCP-first). Your only job: find where a change violates the documented architecture, or where the docs have gone stale relative to the code. No style or generic-quality review.
+
+## Procedure
+
+1. Get the change set (`git diff` / `git diff --staged`, or files named in your prompt).
+2. Check the checklist against the diff. Authoritative rules: `.claude/rules/architecture.md`, `docs/architecture/overview.md`, `docs/architecture/data-model.md`.
+3. Report only violations and doc drift, each with file:line, the rule broken, and the doc stating it. If clean, say so in one line.
+
+## Checklist
+
+**Provider boundary** — LLM client construction or provider SDK usage outside `groundly/llm/`? Hardcoded model/base_url/key? An LLM call path that bypasses `llm/` (and therefore trace cost recording)? A feature that breaks zero-key operation for index/search/submit_* paths?
+
+**Module layering** — anything importing `cli/`, `mcp/`, or `web/` from below? `retrieval` importing `agents`? `ingestion` serving a query path?
+
+**Grounding** — any generation path returning content without resolvable chunk-id citations? Fallback to model knowledge on empty retrieval (must be "not covered")? A community summary used as a citation target?
+
+**Verifier gate** — any write into decks/questions that skips verification (either path)? Code answers accepted without subprocess execution? Missing generation-source recording?
+
+**Storage & concurrency** — SQLite connections without WAL + busy_timeout? Model loading at MCP spawn instead of lazily? `serve` binding non-loopback? Schema change without a `user_version` bump? Export code touching `progress.db`?
+
+**Trust layers** — prompt assembly interpolating retrieved/imported content or notes outside the delimited layer-4 slot? Subject-profile content able to alter grounding rules? Import path missing manifest validation or zip-slip protection?
+
+**Doc drift** — does the change alter behavior a doc states (spec §4/§7, use-case acceptance criteria, interchange format)? Flag the doc; don't edit it yourself.
+
+## Output format
+
+One line per finding: `SEVERITY file:line — rule broken — doc reference`. Severities: `BLOCK` (invariant violated), `DRIFT` (docs stale), `NOTE` (judgment call). End with a one-line verdict.

groundly-0.3.0/.claude/rules/architecture.md

@@ -0,0 +1,29 @@
+# Architecture invariants
+
+Source of truth: `docs/architecture/overview.md`. Violating these is a bug even if tests pass.
+
+## Module boundaries (`groundly/`)
+
+Layers: clients (`cli/`, `mcp/`, `web/`) → services (`agents/`, `retrieval/`, `ingestion/`) → foundations (`llm/`, `core/`).
+
+- Dependencies point one way; **nothing imports the client layer**.
+- `agents` may call `retrieval` (as a tool) and the subprocess runner; `retrieval` never calls `agents`.
+- `ingestion` writes the stores; it never serves queries.
+
+## LLM provider boundary (hard rule)
+
+- LLM clients are constructed **only** in `groundly/llm/` — OpenAI-compatible `base_url` + model + key, **per call class** (`chat`, `generation`, `extraction`, `router`) from `~/.groundly/config.toml`. Never hardcode a provider; cloud keys and LM Studio/Ollama are the same code path.
+- Every LLM call passes through `llm/` and records tokens + cost into the traces table.
+- **Zero-key operation is first-class**: index, `search`, thin `submit_*` generation must never require a provider.
+- Embeddings: `bge-m3`, pinned incl. hf_revision — the pin is the interchange compatibility contract. Changing it = full re-index migration + manifest bump, never a tweak.
+
+## Storage & concurrency
+
+- SQLite **WAL + busy_timeout on every connection** (one-shot CLI and host-spawned MCP share store.db); schema via `PRAGMA user_version`, no migration framework.
+- **Lazy model loading** — never load bge-m3/reranker at MCP spawn; load on first use.
+- `groundly serve` binds **127.0.0.1 only**.
+- Generation jobs are serialized when the provider is a local runtime; never block a request handler on an agent loop.
+
+## Frameworks
+
+Exactly three, one owner each: LlamaIndex (retrieval interface), MS graphrag (graph backend), FastMCP (tool surface). Agent loops are plain bounded async functions — no LangGraph. Exact pins for graphrag/llama-index/docling/sentence-transformers/FlagEmbedding set at P1; upgrades are deliberate events recorded in docs + manifest.

groundly-0.3.0/.claude/rules/conventions.md

@@ -0,0 +1,25 @@
+# Conventions
+
+## Docs are the source of truth
+
+- Decisions live in `docs/groundly-spec.md` §4/§7 with satellite docs; a changed decision updates the docs in the same change set (`/decision`).
+- "Done" for a feature = the acceptance criteria in `docs/use-cases/` pass.
+
+## Python
+
+- Python ≥3.11; typer CLI; FastAPI only inside `groundly serve`; Pydantic v2 + pydantic-settings; type hints on public functions.
+- SQLite schema versioned via `PRAGMA user_version` (checked on open; refuse newer-than-known). Integrity rules as constraints where SQLite allows (unique hashes, FKs), not app code.
+- pytest for tests (no service containers — SQLite files + stub providers); ruff for lint + format.
+- Pin `graphrag`, `llama-index`, `docling`, `sentence-transformers`, `FlagEmbedding` exactly at P1 start; record pins in thesis + export manifest.
+
+## Product surfaces
+
+- MCP tools are the product surface: tool descriptions are UX — write them for the host model. Citations double as MCP resources (`groundly://<subject>/<file>#page=N`).
+- CLI verbs are batch lifecycle only (index/import/export/config/ask); anything conversational belongs to the host agent. No TUI.
+- Long operations print cost estimates before spending the student's tokens and report per-file/per-item progress.
+- User-facing failure messages name the cause specifically ("scanned PDF — not supported"), never generic errors.
+
+## Workflow
+
+- Paul commits himself — leave changes in the working tree.
+- Review diffs with `spec-guardian` (invariants) and `security-reviewer` (threat model) before phase gates.

groundly-0.3.0/.claude/rules/grounding-and-privacy.md

@@ -0,0 +1,26 @@
+# Product invariants: grounding, verification, privacy
+
+The thesis's guarantees (docs/architecture/agents.md, docs/infrastructure/security.md). Never trade them for convenience.
+
+## Grounding
+
+- Every `ask` answer and every stored question/card cites chunk ids that resolve to document + page (+ heading path). Zero resolvable citations = **error**, not a degraded answer.
+- Insufficient context → "not covered by the course materials". No model-knowledge fallback, on any path, ever.
+- Community summaries are never citation targets (no page); citations resolve to verbatim chunks only.
+- `search` is honest best-effort: the host composes. Never claim enforced grounding for host-composed answers; the eval measures the gap.
+
+## Verification gate
+
+- **Nothing unverified enters decks/question banks** — from the thick path (`generate_*`) or the thin path (`submit_*`) alike: answerability by re-retrieval, answer-key check, distractor check, and code **executed in a subprocess** (timeout + tempdir, argv exec, output cap).
+- Rejections return machine-readable reasons. Every stored item records its generation source.
+
+## Trust layers (prompt assembly)
+
+1. immutable system rules > 2. subject profile (size-capped, **trusted content never trusted authority** — cannot disable grounding; applies doubly to imported profiles) > 3. task params > 4. retrieved chunks, graph summaries, imported KB content, recalled notes, user input.
+Layer 4 is **data, never instructions** — delimited and quoted; instructions inside it are inert. Your own PDFs are layer 4 too.
+
+## Privacy & the export boundary
+
+- **The privacy boundary is a file:** `progress.db` (traces = every query asked, quiz history, notes) is **never exported** and never read by export code. `store.db` + `materials/` + `graph/` export whole; the export UX states it plainly.
+- Nothing leaves the machine except calls to the student's own configured provider and HF model downloads. No telemetry, no third-party trace storage.
+- Import is the trust boundary: manifest validated before extraction; zip-slip-safe; imported SQLite opened with schema checks; imported content is layer 4.

groundly-0.3.0/.claude/skills/decision/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: decision
+description: Record or change a Groundly architecture decision consistently across all docs. Use when the user decides, changes, or reverses a tech choice, scope item, or invariant — e.g. "we're switching to Qdrant" or "drop the JupyterLab stretch goal".
+---
+
+# Record an architecture decision
+
+The docs are decision-complete: every choice is stated once as a decision with its decisive reason, never as a menu. Keep it that way.
+
+## Steps
+
+1. **Locate every statement of the affected decision.** Grep `docs/` for the topic. The usual homes: `groundly-spec.md` §4 (component table) and §7 (resolved decisions), plus exactly one satellite doc that owns the detail (`tech-stack/tech-stack.md`, `architecture/*.md`, or `infrastructure/*.md`). Check `.claude/rules/` too — invariants live there in condensed form.
+
+2. **Capture the why.** A decision entry needs: the choice, the decisive reason, and consequences (cost, privacy, migration path). If the user gave no reason, ask for one — "changed our minds" is not auditable in a thesis.
+
+3. **Update all statements in one pass.** Spec table row, spec §7 entry, the owning satellite doc, and any rule file. The old choice becomes the documented alternative/migration path if it remains viable; delete it otherwise.
+
+4. **Check for cascade effects.** Does the change alter the cost model (`infrastructure/cost-model.md`), the distribution story (`infrastructure/distribution.md`), the threat model (`infrastructure/security.md`), the interchange format (`architecture/data-model.md` — a manifest/pin change breaks import compatibility), or an acceptance criterion? Update those too or explicitly note why they're unaffected.
+
+5. **Update project memory** (`groundly-architecture-decisions` memory file) so future sessions treat the new decision as settled.
+
+6. **Report** the changed files and the one-line form of the new decision.

groundly-0.3.0/.claude/skills/implement-uc/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: implement-uc
+description: Implement a Groundly use case (UC-XX) driven by its documented acceptance criteria. Use when starting work on any use case from docs/use-cases/, e.g. "/implement-uc UC-02" or "let's build the mock test generator".
+---
+
+# Implement a use case
+
+Input: a UC id (UC-01…UC-30) or feature name. The acceptance criteria in `docs/use-cases/` define "done" — not vibes.
+
+## Steps
+
+1. **Load the contract.** Read the UC's section in `docs/use-cases/` (knowledge-base / student-modes / sharing). Extract: preconditions, main flow, alternate/error flows, acceptance criteria. Read the referenced architecture docs for the parts this UC touches (`overview.md` for module placement, `data-model.md` for storage + interchange, `retrieval.md`/`agents.md` if applicable).
+
+2. **Check phase order.** Spec §8 maps UCs to phases P1–P7. If this UC depends on machinery from an earlier phase that doesn't exist yet (e.g., UC-12 graph formats need the P5 graph; UC-14 mastery needs P5 communities), say so and confirm scope before coding.
+
+3. **Restate criteria as a test list.** Each acceptance criterion and each alternate flow becomes at least one named test. Include the standing invariant tests that apply (citation resolution for anything generating content; verifier gate for anything writing decks/questions; export-boundary test for anything touching progress.db or export).
+
+4. **Implement inside the module boundaries** (`.claude/rules/architecture.md`): client surface in `cli/`/`mcp/`, logic in the owning service module, LLM access only via `groundly/llm/`, long work as background tasks behind a job id. Tests first where the logic is non-trivial; tests use SQLite files + stub providers, no services.
+
+5. **Verify.** Run the test list; every acceptance criterion must map to a passing test. Report the mapping explicitly (criterion → test name → pass/fail).
+
+6. **Close the loop.** If implementation forced a deviation from the documented flow, update the UC doc in the same change set and say why. Consider running the `spec-guardian` agent on the diff before finishing.

groundly-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  server:
+    name: groundly
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Test (pytest)
+        run: uv run pytest

groundly-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish

groundly-0.3.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Env / secrets
+.env
+.env.*
+
+# User data (never in the repo)
+.unilearn/
+fixtures/
+
+# OS
+.DS_Store

groundly-0.3.0/CLAUDE.md

@@ -0,0 +1,15 @@
+# Groundly
+
+Local-first course knowledge bases for AI agents — index course materials, serve them to MCP hosts (Claude Code/Codex/Desktop) with enforced grounding, verified generation, and a portable interchange format. Bachelor thesis project. Pitch and status: [README.md](README.md).
+
+## Where things are decided
+
+- **Master spec + document map:** [docs/groundly-spec.md](docs/groundly-spec.md) — §4 component decisions, §7 decision register, §8 phasing (P1–P7).
+- **Use-case contracts (acceptance criteria = "done"):** [docs/use-cases/](docs/use-cases/knowledge-base.md)
+- **Architecture:** [overview](docs/architecture/overview.md) · [data-model + interchange](docs/architecture/data-model.md) · [retrieval](docs/architecture/retrieval.md) · [agents](docs/architecture/agents.md)
+- **Stack + LLM provider boundary:** [docs/tech-stack/tech-stack.md](docs/tech-stack/tech-stack.md)
+- **Distribution / security / costs:** [docs/infrastructure/](docs/infrastructure/distribution.md)
+
+## Working rules
+
+Binding invariants auto-load from `.claude/rules/` (module boundaries, grounding guarantees, conventions). Docs are the source of truth — a decision change updates the docs in the same change set (use `/decision`). Implement use cases with `/implement-uc UC-XX`; review with the `spec-guardian` and `security-reviewer` agents. Developer commits himself — leave changes in the working tree for review.

groundly-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Hondola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

groundly-0.3.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: groundly
+Version: 0.3.0
+Summary: Local-first course knowledge bases for AI agents: index your materials, study grounded, share the index.
+License: MIT License
+        
+        Copyright (c) 2026 Paul Hondola
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.13,>=3.11
+Requires-Dist: docling==2.113.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: flagembedding==1.3.5
+Requires-Dist: genanki>=0.13
+Requires-Dist: graphrag==3.1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: llama-index==0.14.23
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13
+Requires-Dist: sentence-transformers==5.6.0
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: eval
+Requires-Dist: ragas>=0.2; extra == 'eval'
+Description-Content-Type: text/markdown
+
+# Groundly
+
+**Local-first course knowledge bases for AI agents.** Index your course materials once; then any MCP-capable agent — Claude Code, Claude Desktop, Codex — can answer questions grounded in the actual course content with page-level citations, generate execution-verified tests and flashcards, quiz your weak areas, and track your mastery. Share the finished knowledge base with your coursemates as a single file.
+
+Bachelor thesis project, Universitatea Politehnica Timișoara.
+
+```
+$ groundly index <SUBJECT> ./slides/
+  ✓ 12 PDFs → 384 chunks → embedded (bge-m3, local) → indexed
+$ # wire into Claude Code:  { "command": "groundly", "args": ["mcp"] }
+```
+
+Then, inside your agent: *"What did lecture 4 say about deadlock prevention?"* → answer cited to **lecture-04.pdf, page 12, "Deadlocks › Prevention"** — or *"not covered by the course materials"*, never a hallucination.
+
+## Why not NotebookLM / a Claude Project?
+
+1. **Verified generation** — every test question and flashcard passes a verifier: answerable from the cited sources, answer key checked, and code questions' reference solutions **actually executed** before acceptance.
+2. **Enforced citations** — structural, page-level, with honest refusal when the corpus doesn't cover it.
+3. **A portable index** — `groundly export <SUBJECT>` → one file; a coursemate imports it and their agent uses it directly. The expensive artifacts (knowledge graph, verified decks) are built once and shared.
+4. **Cross-host progress** — mastery per topic and study memory persist in local files, whatever agent you talk to. Your queries and results never leave your machine and are never part of an export.
+
+## Features
+
+- **Grounded Q&A** — hybrid retrieval (bge-m3 dense + learned sparse + BM25, reranked; optional GraphRAG for synthesis questions), via MCP tools or `groundly ask`
+- **Verified quizzes & coding challenges** — generated by Groundly (your API key) *or by your agent* (no key needed) — either way, nothing unverified is stored
+- **Flashcards → Anki** — verified decks exported as `.apkg`
+- **Mastery map & study memory** — per-topic mastery from quiz results; "continue studying" warm starts in any host
+- **Import/export** — the whole knowledge base as one shareable file, with pinned-model compatibility
+
+## Install
+
+```
+uv tool install groundly
+```
+
+Local-first honestly stated: first run downloads the embedding models (~2.7GB total). Indexing and search need **no API key**; grounded answer generation and graph builds use your own OpenAI-compatible provider (cloud key, LM Studio, or Ollama).
+
+**Thesis core:** four-arm RAG vs GraphRAG evaluation on real RO/EN course corpora, plus a measured comparison of enforced vs agent-mediated grounding.

groundly-0.3.0/README.md

@@ -0,0 +1,38 @@
+# Groundly
+
+**Local-first course knowledge bases for AI agents.** Index your course materials once; then any MCP-capable agent — Claude Code, Claude Desktop, Codex — can answer questions grounded in the actual course content with page-level citations, generate execution-verified tests and flashcards, quiz your weak areas, and track your mastery. Share the finished knowledge base with your coursemates as a single file.
+
+Bachelor thesis project, Universitatea Politehnica Timișoara.
+
+```
+$ groundly index <SUBJECT> ./slides/
+  ✓ 12 PDFs → 384 chunks → embedded (bge-m3, local) → indexed
+$ # wire into Claude Code:  { "command": "groundly", "args": ["mcp"] }
+```
+
+Then, inside your agent: *"What did lecture 4 say about deadlock prevention?"* → answer cited to **lecture-04.pdf, page 12, "Deadlocks › Prevention"** — or *"not covered by the course materials"*, never a hallucination.
+
+## Why not NotebookLM / a Claude Project?
+
+1. **Verified generation** — every test question and flashcard passes a verifier: answerable from the cited sources, answer key checked, and code questions' reference solutions **actually executed** before acceptance.
+2. **Enforced citations** — structural, page-level, with honest refusal when the corpus doesn't cover it.
+3. **A portable index** — `groundly export <SUBJECT>` → one file; a coursemate imports it and their agent uses it directly. The expensive artifacts (knowledge graph, verified decks) are built once and shared.
+4. **Cross-host progress** — mastery per topic and study memory persist in local files, whatever agent you talk to. Your queries and results never leave your machine and are never part of an export.
+
+## Features
+
+- **Grounded Q&A** — hybrid retrieval (bge-m3 dense + learned sparse + BM25, reranked; optional GraphRAG for synthesis questions), via MCP tools or `groundly ask`
+- **Verified quizzes & coding challenges** — generated by Groundly (your API key) *or by your agent* (no key needed) — either way, nothing unverified is stored
+- **Flashcards → Anki** — verified decks exported as `.apkg`
+- **Mastery map & study memory** — per-topic mastery from quiz results; "continue studying" warm starts in any host
+- **Import/export** — the whole knowledge base as one shareable file, with pinned-model compatibility
+
+## Install
+
+```
+uv tool install groundly
+```
+
+Local-first honestly stated: first run downloads the embedding models (~2.7GB total). Indexing and search need **no API key**; grounded answer generation and graph builds use your own OpenAI-compatible provider (cloud key, LM Studio, or Ollama).
+
+**Thesis core:** four-arm RAG vs GraphRAG evaluation on real RO/EN course corpora, plus a measured comparison of enforced vs agent-mediated grounding.

groundly-0.3.0/docs/architecture/agents.md

@@ -0,0 +1,56 @@
+# Agent Layer
+
+Expands [`groundly-spec.md`](../groundly-spec.md) §5b. Governing rule: **agents only where the system must decide, iterate, or use tools mid-task** — everything else is a pipeline. Specialization is data, never code: "which subject" is literally which `~/.groundly/<SUBJECT>/` directory is open. Loops are **plain bounded async functions** — LangGraph was dropped when the roster shrank (consolidation pass).
+
+## The roster (two)
+
+### 1. Ask pipeline — interactive
+
+`router → retrieval arm(s) → fusion/rerank → trust-layered prompt assembly → generation (chat call class) → citation resolution → cited answer or "not covered" → trace row.`
+
+Exposed identically as the MCP `ask` tool and the `groundly ask` CLI verb — **the product tool and the evaluation instrument are one function**. Grounding is enforced inside this boundary: a response with zero resolvable citations is an error; insufficient context returns the refusal, never model knowledge.
+
+Honest scope note: host agents may prefer raw `search` (free, composable) and compose their own answers — that path is best-effort grounding by construction, and the eval *measures* the gap (grounding-fidelity experiment) rather than pretending it away.
+
+### 2. Exam verifier — the identity of generation
+
+Generation is pluggable; **verification is not**. Every question/card entering `store.db` passes, per type:
+
+- **All types:** answerable from the cited chunks alone (confirmed by re-retrieval); answer key correct; distractors actually wrong (MCQ).
+- **Code questions (incl. UC-13 challenges):** the reference solution is **executed in a subprocess** (timeout, tempdir) — compile + run + output matches. A hard guarantee, not an LLM opinion.
+
+Two doors, one gate:
+
+| Path | Generator | Needs API key | Loop |
+|---|---|---|---|
+| Thick: `generate_deck` / `generate_quiz` | Groundly (generation call class) | yes | generate → verify → regenerate, max 2 retries, then drop + note in batch report |
+| Thin: `submit_cards` / `submit_questions` | The host agent, from `search` results | no | verifier returns machine-readable rejections (`not_answerable_from_chunks`, `wrong_answer_key`, `reference_solution_failed`, …); the host regenerates conversationally |
+
+Verified items record their generation source — **rejection rate by source** is a thesis measurement. Verified decks live in `store.db` (exported: one student pays the verification cost, the course imports the deck) and leave the system as Anki `.apkg` via `export_deck`. Forward-compat: the generation interface is shaped so MCP sampling (host-paid tokens, server-controlled loop) can slot in later; not depended on.
+
+## Not agents (deliberately)
+
+- **Gap analysis / study planning** — SQL over `progress.db` quiz events joined to graph communities, plus at most one LLM call to phrase a plan. Weak-area quizzing = the exam path with retrieval weighted toward weak communities.
+- **Study memory** — `recent_activity` is a SQL rollup (by day, not session — stdio lifecycle makes sessions unobservable); `remember`/recall is a table; the `continue-studying` MCP prompt bundles them. No server-side LLM summarization: the consumer is an LLM and narrates structured rollups on demand.
+- **Code tutoring** — the host coding agent does this, grounded via `search`/`ask`. Dropped as a native agent (pivot #2); the enforced Socratic stance was the trade-off, documented.
+
+## Prompt assembly & trust layering
+
+Fixed layers; lower never overrides higher:
+
+| Layer | Content | Mutability |
+|---|---|---|
+| 1. System (immutable) | Grounding rules, citation mandate, refusal on insufficient context | Code, versioned |
+| 2. Subject profile | Notation conventions, emphasis, exam format — per subject, user-editable, shippable in exports | Markdown, **size-capped, trusted content never trusted authority** — cannot disable grounding; imported profiles inherit the same constraints |
+| 3. Task parameters | Subject, topic, difficulty, question types | Request-scoped |
+| 4. Retrieved chunks, graph summaries, **imported KB content**, recalled notes, user input | **Fully untrusted — data, never instructions** | Delimited, quoted; instructions inside are inert by construction of layer 1 |
+
+Imports are the threat that keeps layer 4 honest: a shared knowledge base is third-party content that will enter prompts. Your own lecture PDFs get the same treatment — injection via slides is as real as via imports.
+
+## Latency classes
+
+Interactive (`ask`, `search`): straight pipeline, no background machinery. Generation (decks, quizzes, graph build): background task behind a job id — **never block a request handler on an agent loop**. When the configured provider is a local runtime, generation jobs are serialized (GPU contention with interactive use).
+
+## Observability
+
+Every `ask`/generation run records its trajectory — arm, path, chunk ids, verifier verdicts, tokens, cost, latency — into the `traces` table in **`progress.db`** (personal; never exported; the thesis artifact ships the author's own). Retrofitting logging makes the comparison unreproducible; it exists from P3.