feat(moodle): add source-broker obligation discovery

AGENTS.md

@@ -1,46 +1,19 @@
-# Study Buddy 2.0 Agent Rules
+# Study Buddy Agent Rules
 
-- Study Buddy and upstream T3 Code are separate applications. `t3code-fork/` is Study Buddy-owned fork code; `~/Dokumente/Development/t3code-upstream`, `~/Applications/t3code`, `~/.local/bin/t3-code`, `~/.local/share/applications/t3code.desktop`, `~/.t3`, and `~/.config/t3code` belong to upstream T3 Code unless the user explicitly scopes work there.
-- Study Buddy fork builds must use Study Buddy-specific app identity, state, launcher, protocol, and artifact names. Do not install or copy Study Buddy artifacts into `~/Applications/t3code`, and do not name generated Study Buddy AppImages `T3-Code-*`.
-- Before changing the adaptive interactive Study Builder, read `docs/study-builder-vnext/implementation-charter.md` and the relevant sections of `docs/study-builder-vnext/product-spec.md`; track implementation status in `docs/study-builder-vnext/implementation-plan.md`.
-- Preserve the recognizable Moodle course hierarchy, keep generated practice inside established course scope, and select learning blocks from course and assessment evidence rather than fixed subject templates.
-- Treat every interactive question as a validated bank item with a stable ID, learning objective, answer or rubric, origin, scope basis, stage, and review result.
-- Use only the existing effective Moodle quiz permission. Do not create a shadow permission path or access, start, change, or inspect a quiz beyond that permission.
-- Automatic Study Builder evidence acquisition may inspect authorized completed quiz attempts but must never start or continue an attempt; broader Quiz Assist actions require a separate explicit quiz-assistance request.
-- Keep the adaptive learner runtime to one offline HTML file with compact local state; do not add a backend, account system, detailed attempt history, spaced-repetition scheduler, or user-authored question builder without an explicit charter change.
-- Benchmark adaptive Study Builder changes against `docs/study-builder-vnext/benchmark-manifest.json`; permission, correctness, scope, provenance, and interaction gates remain hard requirements even when optimizing runtime or tokens.
-- Keep all Moodle/CIS pipeline logic isolated under `src/custom-skills/moodle/`.
-- Do not modify host routing, state, or UI files for the Moodle skill.
-- Treat `reference repo Study Buddy 1.0/` as read-only unless the user explicitly asks to modify it.
-- Keep `t3code-fork/` edits minimal, scoped, and merge-friendly; do not place generated study artifacts there.
-- Store Study Buddy pipeline data under `study-buddy-data/`. In regular projects, isolate runs below `threads/<thread-id>/runs/<request-name>/`; in Quick Chats, use `runs/<request-name>/` directly because the workspace is already thread-specific.
-- Keep canonical workflow deliverables inside their run directory, then publish verified user-facing copies outside `study-buddy-data/` in the surrounding workspace.
-- Do not place generated PDFs, Typst files, Markdown drafts, screenshots, diagrams, downloads, or temporary source files inside `t3code-fork/`, `reference repo Study Buddy 1.0/`, or other reference repos.
-- Use the current 2.0 TypeScript contracts for Moodle data shapes, study-document expectations, quiz workflows, and Typst conventions.
-- Govern the Moodle pipeline with LangGraph, not a linear script.
-- Preserve the strict graph state fields: `moodle_raw_text`, `extracted_data`, `final_document`, `error_log`, and `retry_count`.
-- Route invalid analyzer JSON back to the analyzer with `error_log` repair context.
-- Route invalid Typst back to the formatter with validator diagnostics.
-- Abort retry loops after three retries.
-- Expose both a reusable TypeScript API and a CLI wrapper.
-- Prefer live Moodle reads for current information; download linked files only as per-run artifacts when they add usable source text.
-- Prefer live CIS reads for timetable, exam, administrative, and study-program information that Moodle does not expose.
-- For dates, schedules, rooms, exams, and deadlines, use the personal calendar first when configured. One complete direct result from calendar, CIS, or Moodle is sufficient; do not start another run merely to corroborate it.
-- Use CIS directly for attendance and administrative LV information. Use another source only when the primary source is unavailable, has no match, or lacks a requested field.
-- Do not conclude that information is unavailable from one empty source; use the appropriate fallback and report source coverage.
-- Never submit final Moodle quiz attempts.
-- For artifact requests, start one Study Buddy run and monitor that run directory until it reaches a terminal status. Do not launch a second broad crawl while the first run is active.
-- Prefer a direct Moodle course, activity, assignment, or resource URL when one is already known from a completed run.
-- Never reinterpret a requested topic as a neighboring topic such as AC-DC instead of DC-DC. Report source mismatches explicitly.
-- Treat a PDF request as successful only when `run-summary.md` is terminal, `error.log` is empty, and non-empty `document.typ` and `document.pdf` files exist.
-- A reachable dashboard or unrelated course page is not sufficient source coverage for a specific topic.
-- Generated study PDFs must use the standardized Study Buddy Typst component library and document shell.
-- If a run is too broad, cancel it through the wrapper and retry once with the most specific discovered URL. Do not leave superseded runs active.
-- For PDF requests, the Study Buddy `doc` wrapper and standardized Typst renderer are the PDF toolchain. Poll the original command session until exit, or use `study_buddy_task.sh wait <run-dir>`; status checks alone do not complete the task.
-- Do not end the agent turn while an artifact-producing process is still active. After verifying the terminal run and non-empty canonical `document.pdf`, preserve it in the run directory, copy it byte-for-byte to an unused simple `/tmp/<descriptive-filename>.pdf` path, verify the copy, and include `[descriptive-filename.pdf](/tmp/descriptive-filename.pdf)` in the final response so T3 renders the native file attachment icon. Never use `file://`, URL encoding, angle brackets, a workspace/output path as the final delivery link, or a plain-text-only path.
-- Use the buffered lease protocol in `docs/orchestration-lease-protocol.md` for long-running workers: 210 seconds of tool work, 90 seconds reserved for checkpoint generation, and 30 seconds of parent-side delivery grace. For subagents use `wait_agent` with `timeout_ms: 330000`; for PTY processes use one `write_stdin` with `yield_time_ms: 210000`.
-- A long-running worker must checkpoint as `completed`, `progress`, or `blocked` no later than the end of its five-minute lease. Continue the same worker by default when it is alive, on-topic, and making semantic progress.
-- A worker must not begin a blocking operation that can outlive its remaining 210-second work budget. Long processes must run in a reusable session or detached process so the worker can regain control and respond before the five-minute checkpoint deadline.
-- Do not duplicate or replace an active worker because it is quiet. Redirect or replace only on concrete off-course evidence, terminal failure, or stale semantic progress, and confirm the original process has stopped first.
-- Moodle document generation is a mandatory two-worker workflow: `extract` must finish and persist a validated handoff before `render` starts; `render` must consume that handoff without crawling sources again.
-- For Moodle-derived artifacts, never manually create or patch a replacement `.typ`, never call `typst compile` directly, and never generate replacement PDFs in `test*/` or outside the wrapper's printed workflow directory. Rendering recovery must use the official `render` command with the existing successful extraction run. A byte-for-byte `/tmp` delivery copy is permitted only after the canonical workflow PDF has passed all success checks.
+- Study Buddy is a universal study agent, not degree-, course-, subject-, or institution-specific. Build reusable modular behavior that adapts to the user's topic, study context, and configured sources; avoid hard-coded curricula, subject templates, or source assumptions.
+- Study Buddy must coexist with independently installed T3 Code. Never share or alter its identity, state, ports, protocols, launchers, artifacts, updater, migrations, or processes unless explicitly requested.
+- `t3code-fork/` belongs exclusively to Study Buddy. Treat `reference repo Study Buddy 1.0/` as read-only.
+- Keep Moodle and CIS pipeline logic under `src/custom-skills/moodle/`; do not couple it to host routing or UI state.
+- Use the current Study Buddy 2.0 contracts and LangGraph architecture. Preserve `moodle_raw_text`, `extracted_data`, `final_document`, `error_log`, and `retry_count`; stop after three unsuccessful validation retries.
+- Never submit a final Moodle quiz attempt or exceed the existing permission boundary.
+- Before changing Study Builder, read its implementation charter and relevant product specification, then update its implementation plan.
+- Store workflow state under `study-buddy-data/`. Never place generated artifacts inside forks or reference repositories.
+- Use the applicable Study Buddy skill for workflow-specific acquisition, rendering, testing, and delivery procedures.
+
+## Batched Development and Release
+
+- Accumulate compatible fixes and features on the current development version instead of starting or incrementing a release for every change. A batch of roughly 10–20 fixes is a planning heuristic, not a quota or permission to merge unverified work.
+- Give every change focused deterministic tests, a scoped commit, and an entry in the development batch backlog. These checks make a change safe to queue; they do not make the accumulated version release-ready.
+- Freeze the batch deliberately before release. At that point, run the applicable Study Buddy review and release skills, resolve the holistic review findings, and build one exact candidate from the reviewed commit.
+- Because clean packaged acceptance is expensive, reserve full Fedora and Windows VM testing for the exact frozen candidate rather than every small development commit. Any byte change after acceptance invalidates that evidence and requires a rebuilt candidate and fresh affected acceptance.
+- Do not tag, publish, promote, or call a build release-ready without explicit owner approval and the required final review, packaged checks, and clean Fedora/Windows VM acceptance. Never move or reuse a public tag for changed bytes.

docs/development-batch.md

@@ -0,0 +1,21 @@
+# Study Buddy Development Batch
+
+This is the waiting list for changes accumulating before the next release freeze. It records development work, not release acceptance.
+
+## Current line
+
+- Version metadata: `0.2.3-alpha`
+- State: open development batch; not a frozen candidate
+- Version bump, tag, final package, VM release acceptance, and publication: deferred
+
+## Queued changes
+
+| Change | Status | Focused evidence | Final-batch work still required |
+| --- | --- | --- | --- |
+| Prevent the packaged workflow-only `npm` shim from intercepting Codex provider updates | Verified and queued | Exact-commit packaged UI updated an isolated Codex fixture from `0.153.0` to `0.154.0`; provider, Windows/Linux resolution, packaged-runtime, typecheck, and artifact-contract tests passed | Holistic review, final exact-candidate packaging, and clean Fedora/Windows VM acceptance after the batch is frozen |
+
+## Freeze policy
+
+Continue adding compatible, individually tested changes and scoped commits to this line. Roughly 10–20 fixes is a useful batching target, not a hard requirement. When the owner freezes the batch, use the applicable Study Buddy review and release skills, resolve the combined findings, build exact immutable candidate bytes, and test those bytes on clean Fedora and Windows VMs before requesting publication approval.
+
+If candidate bytes change, previous packaged acceptance no longer applies. Public tags are immutable and must never be moved or reused.

docs/moodle-test-service.md

@@ -0,0 +1,80 @@
+# Local Moodle test service
+
+## Scope and current status — 2026-09-08
+
+The owner chose on-demand **local rootless Podman** on the development
+workstation. The earlier Proxmox/tunnel proposal is superseded: do not create
+server guests, publish hostnames, change router rules or involve the separate
+Proxmox MCP implementation.
+
+Commands and input digests are in
+[scripts/moodle-lab/README.md](../scripts/moodle-lab/README.md).
+Implemented: real Moodle bootstrap, synthetic Windows/Fedora student accounts,
+known page/PDF/text fixtures, guarded reset, HTTP acquisition probe and private
+local service control socket. No changes to the personal Study Buddy app.
+
+Verified so far:
+
+- Official Moodle 5.1.6 archive checksum; PHP/PostgreSQL images downloaded and
+  pinned by digest.
+- Both PHP scripts passed PHP 8.4 syntax checks during initial preparation.
+- 13 lightweight tests pass: HTTP cookies, corrupted files, origin rejection,
+  resource preflight, private control socket, reset guards and credential-free status.
+- Low-memory startup refuses before creating containers.
+
+**Pending:** real Moodle installation/seeding/HTTP acceptance, Windows/Fedora
+packaged acquisition and automated guest credential entry. The host has roughly
+4–5 GiB available RAM with nearly full swap; startup requires 9 GiB to retain
+the owner's 8 GiB reserve. No ongoing Moodle service or test VM was started.
+Do not waive this guard or claim these pending checks passed.
+
+## Lifecycle
+
+One foreground service owns two bounded containers (512 MiB PHP / 256 MiB
+PostgreSQL), a private internal network and loopback-only random HTTP port.
+It runs server acceptance before announcing readiness. Agents can request
+status, probe, reset and stop through an owner-only UNIX socket under ignored
+`study-buddy-data/moodle-lab/`. No system service or autostart is installed.
+
+Passwords are synthetic and regenerated each start. Student passwords remain
+in the foreground process; database configuration lives in the private
+temporary fixture tree/container lifetime. Do not collect raw container logs,
+configuration or credential responses as evidence. The credentials command
+is for the owner's private terminal; safe automated guest entry is not
+implemented yet. No API key or university credentials are needed for Moodle.
+
+Stop, Ctrl+C and normal termination remove recorded containers, their
+anonymous volumes, internal network and private temporary data. SIGKILL or
+host crashes cannot guarantee cleanup: inspect only `sb-moodle-check-*`
+resources and validate exact ownership before removal. Cleanup failures
+retain private files for recovery and report failure.
+
+## Remaining local-app integration decision
+
+Study Buddy requires public HTTPS source URLs and rejects loopback/private
+addresses. See `src/custom-skills/moodle/urlSecurity.ts` and the fork's
+`apps/server/src/custom-skills/moodle/browserSecurity.ts`.
+
+The server-only test's explicit HTTP-loopback allowance does **not** change
+application policy. This local service cannot yet be added to an unchanged
+published app. Do not disguise this as a desktop pass, disable TLS/DNS
+protections, expose a public tunnel or silently introduce a production allowlist.
+
+A follow-up needs an explicitly scoped development-test access mechanism,
+including guest transport and credential entry, with production-rejection
+regression tests. If it uses a modified test artifact, label its evidence as
+development integration, not acceptance of unchanged published bytes.
+
+## Acceptance levels
+
+1. **Real server:** valid/invalid login, anonymous denial, student privilege
+   restriction, exact content, guarded reset and identical reseeding.
+2. **Desktop integration:** actual source setup/acquisition in installed
+   Windows/Fedora apps, identifying exact artifact and any test-only config.
+3. **Model-backed guide:** selected app thread using those contents; validate
+   source facts/artifact behavior rather than identical generated wording.
+
+Keep calibrated blank VM snapshots and full app setup, not warmed or
+authenticated snapshots. Codex uses the dedicated ChatGPT subscription handoff.
+Full model-backed generation is deferred for this setup and is not required
+for every unrelated release. Never submit a final quiz.

docs/release-readiness.md

@@ -84,8 +84,52 @@ of the calibrated Windows `clean` and Fedora `clean-wallet` snapshots.
 
 ## Current decision
 
-Status: **blocked for publication while preparation is in progress**.
+Status (2026-09-08): **blocked for publication: targeted Moodle-to-artifact
+acceptance has no recorded successful result**.
 
-The source candidate is being converted to the agreed `0.2.3-alpha` contract.
-No final bundle, exact VM pass, reviewed GitHub draft, or deployed website
-promotion exists yet. Successful source CI alone will not change this decision.
+- Root commit: `0b039abc16b5feb084c8f8c23ac1edfb9f10755d`.
+- UI commit: `24b13681688d3994329ff222759078dd349d812e`.
+- Build: [33491078741](https://github.com/HabsaTheDog/StudyBuddy/actions/runs/33491078741), successful.
+- Root commit checks: successful, including repository policy, pinned UI,
+  Windows/Linux verification, Gitleaks and CodeQL.
+- Windows installer SHA-256:
+  `3b2f6e1e46046d61e7a2852b69efa399689e69c544e95c2736dfbf5849080ef6`.
+- Linux AppImage SHA-256:
+  `13f22eeecf3c86da8011eb3378f3c7e4f4c2521e375902b01d301ca159629820`.
+- Windows standard packaged acceptance: **pass**, 16 scenarios.
+- Fedora standard packaged acceptance: **pass**, 17 scenarios.
+- Both lanes exercised subscription-authenticated synthetic file operations,
+  packaged source-broker/runtime probes, source lifecycle, telemetry,
+  persistence and an upgrade from public `0.2.1-alpha` to these exact bytes.
+- Windows was restored to `clean`; Fedora was restored to `clean-wallet` and
+  booted to verify app/profile/test-workspace absence. Both VMs are shut down.
+- Local evidence: `~/.local/share/study-buddy/release-lab/runs/0.2.3-alpha-run-33491078741/`.
+- GitHub has the complete draft and matching asset digests. Authentication is
+  working. Publication and website promotion were authorized by the maintainer
+  but have not been performed.
+- Bundle checksum verification passed for all ten listed assets. The remote
+  annotated tag resolves to the root commit above.
+- The local website release-selector suite passed (6 tests). The deployed site
+  was inspected and still advertises `0.2.1-alpha`; the draft is excluded.
+  This is not post-publication acceptance of `0.2.3-alpha`.
+- Release-lab helper suite: 41 tests passed. Release-manager skill validation
+  passed after documenting the distinction between generic and targeted gates.
+
+### Remaining release-specific gate
+
+The reported defect concerns a Moodle-backed study guide. The successful saved
+thread exercised synthetic file read/edit/create; the deterministic broker
+probe verifies runtime/environment wiring. Neither proves Moodle acquisition
+through generation of a validated artifact. No successful exact-candidate
+Moodle-to-artifact record was found in the release evidence.
+
+Run that targeted request with an authorized test course/account through the
+exact packaged candidate and record terminal workflow and artifact validation.
+Diagnose any failure before publication. Guest tests used synthetic sources;
+their temporary subscription credentials have been removed. Institution
+credentials were not transferred into the lab.
+
+Afterward, reconcile the draft notes, publish the same accepted bytes, and
+verify anonymous downloads/checksums and deployed website links. Do not repeat
+passing standard scenarios merely because this regression record was missing.
+New development in the dirty checkout is outside this immutable candidate.