cert-coach-web0.1.2

Certification Coach

The problem. Question dumps give you answers without understanding. You memorize a key, pass a practice test, then fail the real exam because the questions are reworded and the concepts were never built. Dumps also go stale, and nothing checks their answers.

The goal. Pass the certification with real understanding — and be able to prove it. This is a one-to-one coach that works one learner at a time: it builds a verified knowledge graph and closes gaps until readiness is ≥ 85% weighted accuracy with ≥ 80% coverage of the gradeable bank.

How it earns trust. Every answer is checked against official documentation before it can be graded; every concept node carries a source URL; nothing is marked confirmed without a check. The agent researches the blueprint, ingests a bank, verifies it, writes a concept DAG + theory reference, then runs probe → plan → teach with spaced retrieval.

What it is not. Not a quiz app, not a summarizer, not a cheat sheet. It will not grade an unverified answer, and it will not answer for the learner.

Where it comes from. Two learning frameworks, archived under docs/archive/:

• Tina Huang — Goal → Research → Priming → Comprehension → Implementation; pretest to prime; fast pass, then layer; note only definitions, major concepts, full examples; interleave; manage energy.
• Eero Alvar — one-to-one teaching; trust engineered through verification; remove logistics, keep the struggle in the material; Probe → Plan → Teach; the plan graph exists to force reasoning; quiz for feedback, calibration, and lock-in.

Who it's for. One learner preparing for one exam at a time, with an AI agent (pi) in the loop.

Status (2026-10-26)

Counts are live in progress.json / /api/status; this is a snapshot.

Cert	Items	Gradeable	Verified	Readiness
DP-600	117	74	105 confirmed · 5 corrected · 7 unverifiable · 0 pending	22%
PL-300	234	155	230 confirmed · 1 corrected · 3 unverifiable · 0 pending	23%
Databricks DA	24	24	24 confirmed · 0 corrected · 0 unverifiable · 0 pending	bootstrap

• Works today: TUI (cert_* tools) + web console (Study, Path, Dashboard, Theory, Logs, teaching chat), Chat v2 (read + research + verify), full mock, live Mermaid, browser cert scaffold, pi auto-install, OpenRouter free-model config.
• Green: 67 tests, both certs validate PASS, npm pack 64 files / no banks.
• Next: npm publish; generated-question review; optional extension slimming.

Quickstart

Web console (recommended)

# from a checkout
npm install
npm pack --dry-run          # verify the tarball; no banks are shipped
node web/bin/cert-coach-web.mjs --cert DP600 --workspace . --pi /path/to/pi-cli

# or once published
npx cert-coach-web --cert DP600

The server opens http://127.0.0.1:<port>/?token=....

The app now uses Editorial Light and the header Studio / Command appearance switch. Studio Triptych is the default; Command Center adds a full-width progress snapshot below the study area. Open http://127.0.0.1:<port>/preview for the static design preview. The quiz loop is server-owned. The right-hand Teaching chat uses pi RPC with a read-only grading profile (cert_status + cert_theory) plus file/research/validation tools (read, web_search, web_fetch, cert_verify), so it teaches but never grades or changes progress.json. pi is auto-installed on first run if missing.

Image exhibits render inline. The SPA includes Study, Path, Dashboard, Theory, and Logs views. The Path view is the route: a 20-question diagnostic Probe → Plan → Progress, with per-domain skills and per-node detail so aggregates cannot hide a gap. It declares the readiness target: weighted readiness ≥ 85% and gradeable coverage ≥ 80%. A mock run is available from idle and does not touch progress. The coach log puts the newest message directly under its title.

Model setup (OpenRouter free)

The teaching chat needs a model. The zero-cost path is OpenRouter's free tier:

1. Sign up free at https://openrouter.ai and create an API key (Keys page; the key starts sk-or-v1-).
2. Configure pi:

   node engine/scripts/configure-openrouter.mjs --key sk-or-v1-...
   

   This writes the key to ~/.pi/agent/models.json and sets defaultModel to a free model (deepseek/deepseek-chat-v3-0324:free, ~164K context). It leaves an existing defaultModel (e.g. a paid deepseek-v4-pro) untouched unless you pass --force. Alternative: set OPENROUTER_API_KEY=sk-or-v1-... in your environment.
3. Restart pi and run /model to confirm.

Free models are rate-limited; for serious study, change defaultModel in ~/.pi/agent/settings.json to a paid model.

Add new dumps or author missing questions

Put new files in <CERT>/raw/ (JSON, HTML, DOCX/Markdown after conversion), then:

node engine/scripts/ingest.mjs <CERT>
node engine/scripts/validate.mjs <CERT>
node engine/scripts/verify_queue.mjs <CERT>
node engine/scripts/build_gap_queue.mjs <CERT>

Ingest merges by md5/stem, preserves verification and progress, and marks new answers pending. verify_queue groups them for doc verification. Interactive dumps with no options/key stay quarantined; build_gap_queue lists them and writes <CERT>/gaps.md + <CERT>/authoring_queue.json, including DAG nodes with zero gradeable questions.

Generated questions are allowed, but they are pending until verified: author them into a JSON source in raw/, ingest, then use cert_verify / apply_verification. Never mark an invented answer confirmed without a source.

Add or switch a certification

Create the new workspace with the agent/TUI first (cert_setup, research, ingest, validate). The workspace needs cert_meta.json, dag.json, bank.json, and progress.json before the server can open it.

Then either launch it directly:

node web/bin/cert-coach-web.mjs --cert AWSSAA --workspace . --pi pi

or use the certification selector in the web header to switch to any existing workspace. Switching stops the old loop/chat, releases the old lock, starts the new cert, and reloads the page. The header + New button scaffolds a new workspace (creates <CERT>/raw/ and <CERT>/extractor.js); the workspace appears in the selector once it has a cert_meta.json. Research and ingest still happen through the agent / TUI (see Add or switch a certification).

TUI

pi --extension ./.pi/extensions/cert-coach.ts

Running pi from WSL

In WSL the pi shell shim passes a Linux path (/mnt/c/...) to the Windows node.exe, which mangles it to C:\mnt\c\... and fails with MODULE_NOT_FOUND. Use the Windows launcher, or run node with a Windows path:

# from PowerShell / cmd
& "C:\palujan\software\node-v24.16.0-win-x64\pi.cmd" update --extensions

# from WSL bash (Windows path to the CLI)
node "C:/palujan/software/node-v24.16.0-win-x64/node_modules/@earendil-works/pi-coding-agent/dist/bundle/cli.js" update --extensions

Upgrading from the old eero-port layout

The plugin now lives in .pi/ and is auto-discovered. If ~/.pi/agent/settings.json still lists eero-port, pi update --extensions fails on the missing path. Back up the file, then remove the two eero-port entries and point visual-tools at the new location:

"packages": [
  "npm:pi-web-search-lite",
  "npm:@eggmasonvalue/pi-subagent",
  "..\\..\\..\\..\\palujan\\files\\projects\\10_projects\\antigravity\\.pi\\extensions\\visual-tools"
]

Then run pi update --extensions again. The teach/visualize skills, the cert-coach/quiz/ask-user-question/md-log extensions, and the prompts load from .pi/ with no install step.

Then say:

prepare me for DP-600

The agent reads the certification-coach skill, asks four questions, researches the blueprint, scaffolds DP600/, and gives you the extractor instructions. When the bank is in raw/, it ingests, validates, and verifies before teaching.

Existing workspace? Say resume DP-600 or run /cert.

What was wrong before

• The DP-600 bank had 38/105 items with no options and no key; PL-300 had 79/235. They were quarantined, not deleted.
• The old ingester keyed progress by array position and stored the answer key as a free string. Progress now uses stable q_<md5> ids and the box/due state survives re-extraction.
• PL-300 was built on the obsolete three-domain blueprint and claimed Visualize was 45–50%. The current official blueprint has four domains: 25–30 / 25–30 / 25–30 / 15–20.
• The old theory contained confident errors (for example, the VACUUM retention parameter and "CALCULATE is the only function that changes filter context"). The DP-600 deep pass also corrects the Direct Lake fallback claim: Direct Lake on OneLake has no DirectQuery fallback; only Direct Lake on SQL analytics endpoints supports fallback via DirectLakeBehavior. Theory is now deep and every node carries a source URL.
• There was no join question → concept node → theory anchor, so "where am I weak?" could only answer at domain level. bank.json now carries node, and theory.md anchors match it.
• The quiz rules and Leitner updates were prose. The cert_* tools now own selection, grading, boxes, due dates, readiness, and the session log.

Layout

.pi/                       the pi plugin (auto-discovered by pi)
  skills/                  5 skills: certification-coach (the brain), battery-ingester,
                           certification-researcher, teach, visualize
  extensions/              cert-coach.ts (cert_* tools), quiz, ask-user-question,
                           md-log, visual-tools/
  prompts/                 researcher, mermaid-maker, svg-maker
engine/                    the pure cert engine (no pi/web coupling)
  core/cert-core.mjs       shared selection/grading/readiness (TUI + web)
  scripts/                 ingest, validate, verify, gap-queue, theory, bundle, export
  extractor.js             browser extractor template ({{CERT}} injected by cert_setup)
  run-script.mjs           cert_run runner (no pi dependency)
server/                    web console server (server-owned StudyLoop, SSE, auth)
public/                    study SPA (Study, Path, Dashboard, Theory, Logs, chat)
  app.js                   wiring: boot, fetch, submit/next, events, listeners
  spa-dom.js spa-store.js  element handles + session store (+ pure helpers)
  spa-question.js          question/feedback/teach/mock cards and the timer
  spa-chat.js              teaching chat: log, streaming, tool cards
  spa-views.js             Path, Dashboard, Theory, Logs, command strip
  spa-ui.js spa-api.js     leaf helpers (notice/layout/log) and the fetch wrapper
  spa-logic.js spa-render.js spa-mermaid.js   URL guards, markdown, Mermaid
bin/                       web console entry point
tests/                     deterministic core/server/web/chat/mock tests
DP600/  PL300/  DATABRICKSDA/  SAPC02/   internal data (shareable as-is; progress.json is owner-only)

Move your own workspace to another PC

For a private move (your own second machine), use the archive script:

powershell -ExecutionPolicy Bypass -File engine/scripts/export_private.ps1

It writes a zip to your Desktop containing the engine and DP600/, PL300/, DATABRICKSDA/, SAPC02/ including raw/, verified bank.json, and vision_assets/. Progress is reset in the archive and study logs are removed by default. Page state (.cert-coach/) and node_modules/ are excluded. Use -KeepProgress to include attempts/history.

On the other PC:

npm install
node web/bin/cert-coach-web.mjs --cert DP600 --workspace . --pi pi

This archive includes exam content — keep it inside your org. The public npm pack stays engine-only (no banks).

Web console

Start the study server:

node web/server/main.mjs --cert DP600 --workspace . --port 0
# opens http://127.0.0.1:<port>/?token=... (or use --no-open)

# JSON API is still available:
# GET /api/state; POST /api/answer; POST /api/next

Run the tests:

node --test tests/core.test.mjs tests/server.test.mjs tests/web.test.mjs tests/chat.test.mjs tests/mock.test.mjs

With the real pi CLI:

node web/bin/cert-coach-web.mjs --cert DP600 --workspace . --pi pi

Committed browser E2E:

npm run test:e2e:chrome          # Chrome CDP smoke
npm run test:e2e:playwright      # Playwright: study, chat/tool, Mermaid, cert switch, mock

Package smoke (packs, installs, and exercises every script cert_run wraps through the shared runner):

npm run test:package

Real-model Playwright smoke:

$env:CERT_COACH_REAL_PI = "C:\path\to\pi-coding-agent\dist\bundle\cli.js"
npm run test:e2e:real

The Chrome test checks question render, no key before submit, feedback, Next, Path, and chat/tool cards. Playwright uses the installed Chrome channel. The header + New button scaffolds a workspace from the browser; research and ingest still run through the agent (see BROWSER_CERT_CREATION.md).

Long chat sessions are compacted automatically so a small-context model never dies mid-study. After 12 learner turns the server starts a fresh pi session and carries a recap of the earlier questions forward; if the model reports a context-limit error anyway, the same compaction happens on the spot and the chat keeps working. Tune the threshold with CERT_COACH_CHAT_MAX_TURNS (or maxTurns on ChatBridge). The chat log shows a dashed session compacted line when it happens.

Mock: choose 10 / 20 / 65 questions and untimed / 90 / 130 minutes before starting. The summary is isolated from progress.json.

Mermaid fences in agent chat/theory now render as live diagrams via a local public/vendor/mermaid.min.js.

Build the single-file bundle:

node engine/scripts/build_bundle.mjs

It writes cert-coach-bundle.md: protocol + extension + extractor + scripts, with <!-- FILE: ... --> markers. Send that one file. The recipient drops it in a project and says:

unpack cert-coach-bundle.md and prepare me for

The agent writes the files, then runs the bootstrap.

DP-600 deep research pass

• Official blueprint re-checked on 2026-10-21 (skills measured as of 2026-10-19; guide last updated 2026-09-18). Domains and weights unchanged; "Query and analyze data" had minor updates.
• Fixed 10 broken Microsoft Learn URLs in DP600/dag.json (OneLake, Delta, shortcuts, pipelines, T-SQL, visual query, Direct Lake fallback, Performance Analyzer, Git, deployment pipelines).
• DP600/theory.md is now a deep, source-backed guide with a DEEP_PASS marker. build_theory.mjs refuses to overwrite it unless --force is used.
• Key correction: Direct Lake on OneLake is DirectLakeOnly and does not fall back to DirectQuery. Only Direct Lake on SQL analytics endpoints supports fallback (Automatic, DirectLakeOnly, DirectQueryOnly), with causes including SQL RLS/DDM/OLS, unmaterialized views, guardrails, framing, and capacity memory.
• Added DAG nodes for onelake_catalog and direct_lake_sql_endpoint to match the official skills.

Eero learning stack (Windows / no-tmux port)

EERO_PORT.md documents the working port of amosblomqvist/learn:

• quiz and ask_user_question — graded concept checks and non-graded questions.
• md-log — /md-log <path.md> mirrors a session to markdown.
• teach and visualize skills — Eero's teaching philosophy and diagram guidance.
• /researcher <question> — isolated child session with web_search / web_fetch.
• /mermaid-maker <brief> and /svg-maker <brief> — author, render, inspect, publish into viz/.
• subagent — cross-platform replacement for the upstream tmux-only subagents.

Use cert_ask for bank items and gap state; use quiz for concept checks while teaching. The two are complementary.

cert_ask shows exhibit images (tables, code, answer areas) inline in the TUI when the terminal supports Kitty/iTerm2 images; otherwise it opens them in your default viewer/browser. Force it with PI_IMAGE_PROTOCOL=kitty or iterm2; disable external auto-open with CERT_COACH_NO_OPEN=1.

Commands

node engine/scripts/ingest.mjs DP600
node engine/scripts/validate.mjs DP600
# or from pi: cert_run({script:"ingest", cert:"DP600"})
node engine/scripts/build_theory.mjs DP600
node engine/scripts/verify_queue.mjs DP600
node engine/scripts/apply_verification.mjs DP600 DP600/verification_pass1.json

Pi: cert_setup, cert_status, cert_ask, cert_next, cert_answer, cert_verify, cert_run, /cert; plus quiz, ask_user_question, subagent, /researcher, /mermaid-maker, /svg-maker, /md-log.

Honest caveats

• DP-600: 74/74 gradeable items verified; ledger 117 items (105 confirmed, 5 corrected, 7 unverifiable, 0 pending). Free half only (21/43 pages) — full coverage needs a paid account and MAX_PAGES.
• PL-300: 155/155 gradeable items verified; ledger 234 items (230 confirmed, 1 corrected, 3 unverifiable, 0 pending). Free half (47/95 pages). manage_secure is ~14.5% of the bank vs the 15–20% blueprint.
• Image items are not lost. 42 DP-600 / 79 PL-300 items depend on exhibits or code images. They are marked needs_vision with asset URLs; a vision pass can recover them.
• Data is internal-shareable, as-is. DP600/, PL300/, DATABRICKSDA/, and SAPC02/ (banks, raw/, vision_assets/) ship in the internal package only, never the public npm tarball. Scraping is still subject to the source site's terms, so keep the internal export inside your org. progress.json is owner-only and reset on export.
• The extension is pi-only. The portable protocol is the certification-coach skill; the deterministic state layer requires pi.