Skip to content

HANDOVER.md

Latest commit

 

History

History
215 lines (156 loc) · 12.6 KB

HANDOVER.md

File metadata and controls

215 lines (156 loc) · 12.6 KB
Raw

Handover: terraphim.ai

Latest session: Graph Embeddings Interactive Explainer + WASM + Promotion (2026-10-20)

Repo state: main at 854cdb3, pushed and deployed. Only HANDOVER.md (this file) is uncommitted — it is a working document, commit it when convenient.

Docs alignment (2026-10-21): content/how-tos/_index.md now has a "Recently published" card row surfacing the latest posts (explainer, checklists, book announcement, token saving, Skills 54, cold-start tax) above the three evergreen guides; content/docs/graph-embeddings.md links to the interactive explainer. Docs-repo PR terraphim/terraphim-ai#1006 merged (a056e7a, commit c5a6b7f): docs/src/scorers/graph-embedding-analysis.md and terraphim-graph.md both carry a "See it running" pointer to the WASM explainer. Verified live on docs.terraphim.ai (note: pages serve at extensionless URLs — src/scorers/X — after a 308 from .html). One deploy flake: self-hosted runner had a stale /tmp/md-book blocking the md-book clone; cleaned on bigbox, rerun green (build + production deploy + CDN purge).

What was done

Interactive explainer live at https://terraphim.ai/docs/graph-embeddings-interactive/

  • Visual explainer teaching Terraphim graph embeddings to non-experts, running the real terraphim_rolegraph Rust crate compiled to WebAssembly in the browser (not a JS port — see lessons below).
  • Scenes: two retrieval worlds (dense vectors vs graph), live Aho-Corasick matcher, step-by-step indexing, query ledger decomposing every score into node + edge + doc contributions, add-synonym with measured automaton rebuild, honest limitations.
  • Verified live: 10 concepts · 23 directed edges · 8 documents · 19 thesaurus terms; consensus ledger 19 = 7+1+2 + 7+1+1 matching the Python oracle; OOV byzantine fault tolerance returns an honest empty set; café multibyte spans highlight correctly.

Key files

File Purpose
content/docs/graph-embeddings-interactive.md Page copy
templates/explainer.html Template
static/explainers/graph-embeddings/explainer.js UI/scenes (DOM only)
static/explainers/graph-embeddings/engine.js Thin adapter over WASM — no algorithm
static/explainers/graph-embeddings/wasm/ Compiled wasm-bindgen bundle + wasm-manifest.json provenance
scripts/explainer/rolegraph-wasm/ Vendored wrapper crate source (canonical copy should land in terraphim-core; the core worktree terraphim-core-wt86 has it uncommitted on drop-slim)
scripts/explainer/check.js + oracle.py + goldens.json 20-check conformance suite: WASM nodejs build vs independent Python oracle
scripts/explainer/build-wasm.sh Rebuilds artifacts from vendored source, records core commit + sha256

Promotion campaign — all receipts in publication/graph-embeddings-interactive/ (commit 51b9cc4):

Channel URL
X thread (6 posts) + Article x.com/alex_mikhalev/status/2112565593446740253 … /2112566105692647839; article /2112566613023109499
Discord #terraphim discord.com/channels/852545081613615144/852550167130931230/1562122870971306015
Discourse terraphim.discourse.group/t/…/31
GitHub Discussion github.com/orgs/terraphim/discussions/30
dev.to / Medium canonical-linked articles live
Mastodon / Reddit r/TerraphimAI live

LinkedIn copy drafted but unpublished (prior campaign boundary); YouTube/r/rust/brandX skipped.

Notable loose ends

  • The terraphim_rolegraph wasm32 Cargo fix (tokio target-gate) and the wasm/ wrapper crate exist uncommitted in terraphim-core-wt86 on drop-slim — the published crate 2.0.1 already carries the equivalent fix upstream, so the worktree edit is redundant; the vendored website copy is the reproducible source of truth for the deployed artifact.
  • terraphim-editor's crates/terraphim_rolegraph_browser already provides a stricter session-protocol WASM bridge (verified: wasm32 compiles, 23 tests pass). Optional refactor: adopt its BrowserRoleGraph JSON-envelope API for the explainer instead of the specialised façade.
  • GitHub merge flow needs --admin when the authenticated user authored the PR (self-review can't satisfy branch protection). gh pushes via git -c credential.helper='!gh auth git-credential' (SSH blocked).

Previous session: Full Publication + Benchmark Pipeline + Search Fix (2026-04-16)

All three repos clean on main at time of writing.

What Was Done

1. Three Sites Published with CI

Site URL Deploy CI Workflow Status
terraphim.ai https://terraphim.ai Cloudflare Pages .github/workflows/deploy.yml (new) Live
docs.terraphim.ai https://docs.terraphim.ai Cloudflare Pages deploy-docs.yml (existing) Live
terraphim.rs https://terraphim.rs Cloudflare Pages .github/workflows/deploy.yml (new) Live

2. Landing Page Overhaul (terraphim.ai)

  • Hero leads with cargo install terraphim-agent install block + copy button
  • Hyperdrive stat renamed: "Pattern Engine: Aho-Corasick" to "Graph Embeddings"
  • Core Capabilities expanded from 7 to 9: added Graph Embeddings, terraphim-agent CLI, Multi-Haystack Search; Origin Story moved to footnote link
  • Deploy Everywhere expanded from 4 to 8: CLI, Desktop, HTTP Server, MCP Server, Browser Extension, Node/npm, Python/PyO3, Edge and Embedded
  • How-Tos nav created with command-rewriting howto
  • Inline styles added: .inline-link (solid amber underline), .inline-code (JetBrains Mono), .hero-install, .section-footnote
  • Em-dashes replaced across 17 files (96 instances)

3. Ship Systems: Fabricated Metrics Replaced with Real Data

Hardcoded fictional numbers replaced with values from the Criterion bench suite:

  • Inference 5-10 ns, search < 1 ms, graph 15-20 MB, index build ~301 us / ~3.66 ms, throughput ~310 MiB/s
  • Metrics now rendered via Zola load_data("content/data/benchmarks.json")
  • Visible "Last measured 2025-11-11" timestamp in footnote

4. Benchmark Pipeline (Gitea #574) — All 3 Steps Complete

Step Commit Repo Description
1 82e575a terraphim.ai content/data/benchmarks.json + Tera load_data
2 47960199 terraphim-ai scripts/update-benchmark-snapshot.sh + CI commit step
3 05a6a2fe terraphim-ai publish-benchmarks-to-site.yml rewritten to use self-hosted runner + 1Password (no GitHub PAT secret needed)

End-to-end flow: Criterion bench on terraphim-ai main -> snapshot.json committed -> publish-benchmarks-to-site.yml fires on self-hosted runner (bigbox) -> 1Password injects GH_TOKEN -> PR opened on terraphim.ai -> human merges -> deploy.yml fires -> Cloudflare deploys fresh numbers.

5. Search Fixed (Critical Bug)

Bug: all search result links pointed to https://terraphim.ai/undefined. Zola's elasticlunr index uses the full URL as the document ref (ID), not as a url field on the doc object. The JS at site.js:147 read item.url which was undefined.

Fix: item.url -> result.ref (commit 1b79bd7).

Verified via dev-browser: Ctrl+K opens modal, queries return correct results with working links, click navigates to the right page, Escape closes modal.

6. Learning Capture How-Tos Published on docs.terraphim.ai

Two articles moved to docs/src/howto/ and added to SUMMARY.md:

  • learning-capture-claude-code.md — cross-checked against actual ~/.claude/hooks/
  • learning-capture-opencode.md — cross-checked against actual ~/.config/opencode/plugin/terraphim-hooks.js

Fixes: architecture diagram bug, non-existent command removed, safety guard + replace pipeline documented for opencode, tilde-in-require fixed, plugin file list updated, cross-links added.

7. Cleanup

  • Stale deploy-website.yml deleted from terraphim-ai
  • terraphim.rs initialised as git repo, pushed to github.com/terraphim/terraphim.rs
  • Issue #772 (bench script bash syntax error) confirmed already fixed, closed
  • .env.1password vault references fixed by user (TerraphimPlatform/terraphim-md-book-cloudflare)

What Needs Doing

Blocking (one-off manual, activates the benchmark pipeline)

Action Detail
Create 1Password item github-site-deploy Fine-grained GitHub PAT scoped to terraphim/terraphim.ai (contents:write + pull-requests:write). Store in TerraphimPlatform vault, field credential. Reference: op://TerraphimPlatform/github-site-deploy/credential.
Smoke-test benchmark sync Push benchmark-results/snapshot.json to terraphim-ai main (or trigger workflow_dispatch on publish-benchmarks-to-site.yml). Verify PR opens on terraphim.ai with label benchmarks.
Close Gitea #574 After smoke-test: gtr close-issue --owner terraphim --repo terraphim-ai --issue 574

Planned (ready for implementation)

Item Plan location Detail
Light theme for terraphim.ai /Users/alex/.claude/plans/lovely-herding-brook.md 5-step plan: extract hardcoded colours -> light palette -> hide star-field -> toggle button -> WCAG audit. ~4.5h. Plan approved but not yet started.

Non-blocking (future)

Item Detail
Wire more Criterion benches to snapshot inference_ns, search_latency_ms, graph_footprint_mb, index_throughput_mibps are static fallbacks; need Criterion bench IDs mapped
Optional ADF nightly flow Add benchmark-publisher-flow to orchestrator.example.toml for nightly snapshot generation independent of CI
Orphan pages (/json/, /json-ad/) Intentional machine-readable endpoints; Zola warning is cosmetic; no action needed

Key Files

terraphim.ai

File Purpose
config.toml Nav: Home, Capabilities, How-tos, Docs, Rust, Releases, Install, Donate
themes/WarpDrive/templates/index.html Homepage: hero install, 9 capabilities, Ship Systems via load_data, 8 deploy targets
themes/WarpDrive/static/js/site.js Search (elasticlunr), platform detection, scroll gauge, copy buttons
themes/WarpDrive/static/css/warp.css Theme CSS (~2350 lines)
content/data/benchmarks.json Canonical benchmark snapshot (consumed by Ship Systems section)
content/capabilities/*.md 9 capability pages + origin-story
.github/workflows/deploy.yml CI: Zola build + Cloudflare Pages deploy

terraphim-ai (relevant session changes)

File Purpose
scripts/update-benchmark-snapshot.sh Extracts Criterion means into snapshot.json
.github/workflows/performance-benchmarking.yml Extended: runs snapshot script after baseline update
.github/workflows/publish-benchmarks-to-site.yml Cross-repo PR via self-hosted runner + 1Password
docs/src/howto/learning-capture-*.md Two how-to articles
docs/src/SUMMARY.md Added How-Tos section

terraphim.rs

File Purpose
index.html Static landing page
.github/workflows/deploy.yml CI auto-deploy to Cloudflare Pages

Commit Log (session)

terraphim.ai

1b79bd7 fix(search): use result.ref as URL instead of undefined item.url
5c2ba05 style: replace double-dash with em dash across copy
82e575a feat(ship-systems): render metrics from content/data/benchmarks.json
3a57d0d feat: hero install one-liner, 9 capabilities, 8 deploy targets
da64c9f style: strengthen inline links, subdue code chips in footnote
c6cf4bb style: style inline links and code in Ship Systems section
1bd1b5e feat: replace fabricated Ship Systems metrics with real benchmark data
f28b9db feat: add How-Tos nav section and move command-rewriting guide
a570a25 ci: add Cloudflare Pages auto-deploy workflow

terraphim-ai

05a6a2fe fix(ci): use self-hosted runner + 1Password for benchmark sync
1de2c966 docs: publish learning-capture howtos with cross-checked fixes
674c6b6b feat(bench): add cross-repo workflow to publish snapshot to terraphim.ai
47960199 feat(bench): emit headline snapshot.json for terraphim.ai consumption
cea40f96 chore: remove stale deploy-website workflow
32b8a505 chore: merge github/main to sync diverged histories

terraphim.rs

be508ef ci: add Cloudflare Pages auto-deploy
fc05651 chore: initial commit

Research and Design Artefacts

Document Location Purpose
Research: Ship Systems benchmarks .docs/research-ship-systems-benchmarks.md (gitignored) Phase 1: maps existing bench infra, identifies 4 bridge options, recommends Option A
Design: Ship Systems benchmarks .docs/design-ship-systems-benchmarks.md (gitignored) Phase 2: 3-step plan with JSON schema, Tera template, CI changes
Plan: Light theme ~/.claude/plans/lovely-herding-brook.md 5-step plan: extract colours, light palette, hide star-field, toggle, WCAG audit