@hanzlaa/rcode 2.8.0 → 3.1.0

package/rihal/skills/core/rihal-clone-website/references.md

@@ -0,0 +1,213 @@
+# Clone Website — Detailed Reference
+
+Detailed principles, scripts, templates, and checklists for [`SKILL.md`](SKILL.md). Keep this file open in another tab while running the skill.
+
+---
+
+## 9 Guiding Principles
+
+These are the truths that separate a successful clone from a "close enough" mess.
+
+### 1. Completeness beats speed
+Every builder agent must receive **everything** it needs: screenshot, exact CSS values, downloaded assets with local paths, real text content, component structure. If a builder has to guess any value, extraction failed. One extra minute of extraction beats an incomplete brief.
+
+### 2. Small tasks, perfect results
+Builder prompts ≤150 lines of spec. If a section's spec exceeds that, split it: one agent per sub-component plus one for the wrapper. Don't override with "but it's all related."
+
+### 3. Real content, real assets
+Extract actual text, images, videos, SVGs from the live site. Use `element.textContent`, download every `<img>` and `<video>`, extract inline `<svg>` as React components. Layered assets matter — a section that looks like one image is often multiple layers (background, foreground UI mockup, overlay icon). Inspect the full DOM tree.
+
+### 4. Foundation first
+Sequential and non-negotiable: global CSS with the target's design tokens, TypeScript types for content structures, global assets (fonts, favicons). Everything after this can be parallel.
+
+### 5. Extract how it looks AND how it behaves
+Static CSS alone produces dead-feeling clones. For every element extract appearance (`getComputedStyle`) AND behaviour (what changes, what triggers it, how the transition runs). Behaviours to watch: scroll-shrink navbars, viewport-entry animations, scroll-snap, parallax, hover transitions, modals/accordions, auto-play carousels, scroll-driven tab switching, smooth-scroll libraries (Lenis, Locomotive Scroll).
+
+### 6. Identify the interaction model before building
+The single most expensive mistake: building click-based UI when the original is scroll-driven (or vice versa).
+- Scroll first, slowly. Watch for self-changing elements.
+- If something changes on scroll, it's scroll-driven. Extract the mechanism.
+- Only THEN test for click/hover-driven interactivity.
+- Document the interaction model explicitly in every spec.
+
+### 7. Extract every state, not just the default
+For tabbed/stateful content: click each tab via Chrome MCP, extract per state. For scroll-dependent elements: capture at scroll position 0 and after crossing the trigger threshold.
+
+### 8. Spec files are the source of truth
+Every component gets a spec file in `docs/research/components/` BEFORE any builder is dispatched. The builder receives the spec contents inline; the file persists as an auditable artefact.
+
+### 9. Build must always compile
+Every builder verifies `npx tsc --noEmit` before finishing. After merging worktrees, you verify `npm run build` passes. No red merges.
+
+---
+
+## Asset Discovery Script (Chrome MCP)
+
+```javascript
+JSON.stringify({
+  images: [...document.querySelectorAll('img')].map(img => ({
+    src: img.src || img.currentSrc,
+    alt: img.alt,
+    width: img.naturalWidth,
+    height: img.naturalHeight,
+    parentClasses: img.parentElement?.className,
+    position: getComputedStyle(img).position,
+    zIndex: getComputedStyle(img).zIndex
+  })),
+  videos: [...document.querySelectorAll('video')].map(v => ({
+    src: v.src || v.querySelector('source')?.src,
+    poster: v.poster,
+    autoplay: v.autoplay, loop: v.loop, muted: v.muted
+  })),
+  backgroundImages: [...document.querySelectorAll('*')].filter(el => {
+    const bg = getComputedStyle(el).backgroundImage;
+    return bg && bg !== 'none';
+  }).map(el => ({
+    url: getComputedStyle(el).backgroundImage,
+    element: el.tagName + '.' + el.className?.split(' ')[0]
+  })),
+  fonts: [...new Set([...document.querySelectorAll('*')].slice(0, 200).map(el => getComputedStyle(el).fontFamily))],
+  favicons: [...document.querySelectorAll('link[rel*="icon"]')].map(l => ({ href: l.href, sizes: l.sizes?.toString() }))
+});
+```
+
+---
+
+## CSS Extraction Script (per section, replace `SELECTOR`)
+
+```javascript
+(function(selector) {
+  const el = document.querySelector(selector);
+  if (!el) return JSON.stringify({ error: 'Element not found: ' + selector });
+  const props = [
+    'fontSize','fontWeight','fontFamily','lineHeight','letterSpacing','color',
+    'textTransform','textDecoration','backgroundColor','background',
+    'padding','paddingTop','paddingRight','paddingBottom','paddingLeft',
+    'margin','marginTop','marginRight','marginBottom','marginLeft',
+    'width','height','maxWidth','minWidth','maxHeight','minHeight',
+    'display','flexDirection','justifyContent','alignItems','gap',
+    'gridTemplateColumns','gridTemplateRows',
+    'borderRadius','border','borderTop','borderBottom','borderLeft','borderRight',
+    'boxShadow','overflow','overflowX','overflowY',
+    'position','top','right','bottom','left','zIndex',
+    'opacity','transform','transition','cursor',
+    'objectFit','objectPosition','mixBlendMode','filter','backdropFilter',
+    'whiteSpace','textOverflow','WebkitLineClamp'
+  ];
+  function extractStyles(element) {
+    const cs = getComputedStyle(element);
+    const styles = {};
+    props.forEach(p => {
+      const v = cs[p];
+      if (v && v !== 'none' && v !== 'normal' && v !== 'auto' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)') styles[p] = v;
+    });
+    return styles;
+  }
+  function walk(element, depth) {
+    if (depth > 4) return null;
+    const children = [...element.children];
+    return {
+      tag: element.tagName.toLowerCase(),
+      classes: element.className?.toString().split(' ').slice(0, 5).join(' '),
+      text: element.childNodes.length === 1 && element.childNodes[0].nodeType === 3 ? element.textContent.trim().slice(0, 200) : null,
+      styles: extractStyles(element),
+      images: element.tagName === 'IMG' ? { src: element.src, alt: element.alt, naturalWidth: element.naturalWidth, naturalHeight: element.naturalHeight } : null,
+      childCount: children.length,
+      children: children.slice(0, 20).map(c => walk(c, depth + 1)).filter(Boolean)
+    };
+  }
+  return JSON.stringify(walk(el, 0), null, 2);
+})('SELECTOR');
+```
+
+---
+
+## Component Spec Template
+
+Save to `docs/research/components/<component-name>.spec.md`:
+
+```markdown
+# <ComponentName> Specification
+
+## Overview
+- **Target file:** `src/components/<ComponentName>.tsx`
+- **Screenshot:** `docs/design-references/<screenshot-name>.png`
+- **Interaction model:** <static | click-driven | scroll-driven | time-driven>
+
+## DOM Structure
+<hierarchy>
+
+## Computed Styles (exact values)
+### Container
+- display, padding, maxWidth, etc.
+
+### <Child element>
+- every relevant property
+
+## States & Behaviors
+### <Behavior name>
+- **Trigger:** <exact mechanism>
+- **State A (before):** CSS values
+- **State B (after):** CSS values
+- **Transition:** transition CSS
+- **Implementation approach:** <CSS transition | IntersectionObserver | etc.>
+
+## Assets
+- Background/overlay images with paths
+- Icons used from icons.tsx
+
+## Text Content (verbatim)
+<copy-pasted from live site>
+
+## Responsive Behavior
+- Desktop (1440px): <layout>
+- Tablet (768px): <changes>
+- Mobile (390px): <changes>
+- Breakpoint: ~<N>px
+```
+
+---
+
+## Pre-Dispatch Checklist (every builder, every time)
+
+- [ ] Spec file written with ALL sections filled
+- [ ] Every CSS value is from `getComputedStyle()`, not estimated
+- [ ] Interaction model identified and documented
+- [ ] All states captured (not just default)
+- [ ] Scroll/hover triggers with before/after/transition recorded
+- [ ] All images identified including overlays
+- [ ] Responsive behavior documented
+- [ ] Text content verbatim
+- [ ] Builder prompt ≤150 lines
+
+---
+
+## What NOT to Do
+
+- Don't build click-based tabs when the original is scroll-driven
+- Don't extract only the default state of tabbed content
+- Don't miss overlay/layered images
+- Don't build HTML mockups for content that's actually videos / Lottie / canvas
+- Don't approximate CSS classes — extract exact values
+- Don't build monolithic commits
+- Don't reference external docs from builder prompts — inline everything
+- Don't skip asset extraction
+- Don't give a builder too much scope
+- Don't bundle unrelated sections into one agent
+- Don't skip responsive extraction at 1440 / 768 / 390
+- Don't forget smooth scroll libraries (Lenis, Locomotive)
+- Don't dispatch builders without a spec file
+
+---
+
+## Final Completion Report Format
+
+```
+Total sections built:        N
+Total components created:    N
+Total spec files written:    N   (must match components)
+Total assets downloaded:     N   (images / videos / SVGs / fonts)
+Build status:                PASS | FAIL
+Visual QA discrepancies:     <remaining diffs>
+Known gaps / limitations:    <list>
+```

package/rihal/skills/core/rihal-deploy-unify/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: rihal-deploy-unify
+description: Detect and unify multiple deployment paths in a single project. Use when a repo has accumulated overlapping deploy mechanisms (Docker Compose + Helm + manual scripts + Vercel + Jenkins) and "which one runs in production" is unclear. Specifically encodes the Siraaj deployment chaos lesson — multiple deploy paths cost a week of debugging and broke Keycloak more than once.
+triggers:
+  - "deploy unify"
+  - "multiple deploy paths"
+  - "which deploy is production"
+  - "deploy chaos"
+  - "consolidate deployments"
+  - "kubernetes vs compose"
+  - "single deploy path"
+  - "deployment audit"
+user-invocable: true
+---
+
+## Overview
+
+Multiple deploy paths is a shipping-risk multiplier. Every path is one more thing that can drift from the others, deploy stale code, or "I thought you ran it" through ops. The Rihal Siraaj incident was a textbook case — Docker Compose for some services, Helm for others, manual `ssh && pull` for the rest, and no one knew which combination was production.
+
+## Workflow
+
+1. **Inventory every deploy path.** Look in:
+   - `docker-compose.yml`, `docker-compose.*.yml`
+   - `helm/`, `charts/`, `k8s/`
+   - `Makefile`, `scripts/deploy*`
+   - `.github/workflows/deploy*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`
+   - Vercel / Netlify project links
+   - Anything in `infra/` or `deployment/`
+2. **Classify each:** dev / staging / production. If you can't classify it, that's the bug.
+3. **Identify drift.** For each pair (dev↔staging, staging↔prod):
+   - Different env vars?
+   - Different image tags?
+   - Different replica counts?
+   - Different healthchecks?
+   - Different secret-management?
+4. **Pick ONE canonical path per environment.** Helm + values per env is the rcode default. Compose is dev-only. No "and also a Jenkinsfile that does it differently".
+5. **Deprecate the others** with a clear timeline. Don't delete on day one — leave them as `*.deprecated` and observe for 2 weeks before removal.
+6. **Document the canonical path** in `.rihal/memory/project/decisions.md` and a top-level `DEPLOYMENT.md`.
+
+## Common drift patterns to look for
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| "Works in staging, breaks in prod" | Different env vars between paths | Single source of truth (Helm values + sealed-secrets) |
+| Image tags lag behind git SHA | Manual `docker push` mid-week | Tag-based deploys via CI only |
+| Healthchecks pass in compose, fail in K8s | Compose uses HTTP, K8s uses TCP | Align probe definitions |
+| "Deploy" doesn't restart all services | Some compose, some bare metal | One orchestrator |
+| Secrets diverge | `.env` files copied manually | External Secrets Operator or sealed-secrets only |
+
+## Output Format
+
+```
+Deploy paths discovered: <count>
+  - <path 1> — <classification>
+  - <path 2> — <classification>
+  ...
+
+Drift findings:
+  ✗ <pair> — <specific drift>
+  ✗ <pair> — <specific drift>
+
+Canonical path proposal:
+  dev:        <one path>
+  staging:    <one path>
+  production: <one path>
+
+Deprecation plan:
+  Week 1: mark <X> as deprecated, route docs to canonical
+  Week 2: remove <X> if no fallback usage observed
+
+Memory Bank update:
+  → .rihal/memory/project/decisions.md (canonical path decision)
+  → DEPLOYMENT.md (the runbook)
+```
+
+## Examples
+
+**Happy path — Siraaj-style mess** — 4 deploy paths found: docker-compose (dev), Helm (staging), manual script (prod-mostly), Jenkinsfile (sometimes prod). Drift: 6 envs differ between staging and prod. Canonical: Helm with `values.staging.yaml` and `values.production.yaml`. Compose stays dev-only. Manual + Jenkinsfile deprecated, removed 2 weeks later.
+
+**Edge case — legitimate dual path** — Mobile app uses TestFlight + Play Console; web uses Vercel. These are different surfaces, not deploy-path drift. Document why each surface uses what it does; don't try to unify across surfaces.
+
+**Negative — "let's just delete the old paths"** — Refuse without observation period. Some "deprecated" paths are actually the only thing that works for a specific service. Mark, observe, then delete.
+
+## Memory Bank Hooks
+
+- **Reads:** `.rihal/memory/incidents/post-mortems/` (prior deploy incidents)
+- **Writes:** `.rihal/memory/project/decisions.md` (canonical path decision); `.rihal/memory/change-records/YYYYMMDD-NNN.md` (the unification itself as a change record)

package/rihal/skills/core/rihal-distillator/SKILL.md

@@ -1,213 +1,63 @@
 ---
 name: rihal-distillator
-description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
-argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]"
+description: Lossless LLM-optimized compression of source documents. Use when the user requests to "distill documents" or "create a distillate". Distillates preserve every fact, decision, constraint, and relationship while stripping prose overhead — designed as drop-in LLM context. Not summarisation (summaries are lossy). For Memory Bank distillates specifically, use rcode-memory-distill.
+argument-hint: "<source-paths> [--validate <distillate-path>] [--token-budget <N>] [--consumer <name>]"
 triggers:
   - "distillator"
+  - "distill documents"
+  - "create a distillate"
+  - "compress these docs"
+user-invocable: true
 ---
 
-# Distillator: A Document Distillation Engine
-
 ## Overview
 
-This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
-
-This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
-
-## On Activation
-
-1. **Validate inputs.** The caller must provide:
-   - **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
-   - **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
-   - **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
-   - **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
-   - **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
-
-2. **Route** — proceed to Stage 1.
-
-## Stages
-
-| # | Stage | Purpose |
-|---|-------|---------|
-| 1 | Analyze | Run analysis script, determine routing and splitting |
-| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
-| 3 | Verify & Output | Completeness check, format check, save output |
-| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
-
-### Stage 1: Analyze
-
-Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
-
-### Stage 2: Compress
-
-**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
-
-Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
-
-**Fan-out mode** (routing = `"fan-out"`):
-
-1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
-
-2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
-
-3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
-
-**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
-
-The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
-
-### Stage 3: Verify & Output
-
-After the compressor (or merge compressor) returns:
-
-1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
-
-2. **Format check.** Verify the output follows distillate format rules:
-   - No prose paragraphs (only bullets)
-   - No decorative formatting
-   - No repeated information
-   - Each bullet is self-contained
-   - Themes are clearly delineated with `##` headings
-
-3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
-
-   **Single distillate** (≤~5,000 tokens or token_budget not exceeded):
-
-   Save as a single file with frontmatter:
-
-   ```yaml
-   ---
-   type: rihal-distillate
-   sources:
-     - "{relative path to source file 1}"
-     - "{relative path to source file 2}"
-   downstream_consumer: "{consumer or 'general'}"
-   created: "{date}"
-   token_estimate: {approximate token count}
-   parts: 1
-   ---
-   ```
-
-   **Split distillate** (>~5,000 tokens, or token_budget requires it):
-
-   Create a folder `{base-name}-distillate/` containing:
+Compresses source documents into a dense, lossless distillate optimised for LLM context loading. Output is one (or several semantically split) markdown files containing every fact, decision, named entity, and relationship from the sources — but no prose connectives, decoration, or repetition. A downstream LLM can use the distillate as sole context with no information loss.
 
-   ```
-   {base-name}-distillate/
-   ├── _index.md           # Orientation, cross-cutting items, section manifest
-   ├── 01-{topic-slug}.md  # Self-contained section
-   ├── 02-{topic-slug}.md
-   └── 03-{topic-slug}.md
-   ```
+## Process
 
-   The `_index.md` contains:
-   - Frontmatter with sources (relative paths from the distillate folder to the originals)
-   - 3-5 bullet orientation (what was distilled, from what)
-   - Section manifest: each section's filename + 1-line description
-   - Cross-cutting items that span multiple sections
-
-   Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
-
-   Source paths in frontmatter must be relative to the distillate's location.
-
-4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
-
-5. **Report results.** Always return structured JSON output:
-
-   ```json
-   {
-     "status": "complete",
-     "distillate": "{path or folder path}",
-     "section_distillates": ["{path1}", "{path2}"] or null,
-     "source_total_tokens": N,
-     "distillate_total_tokens": N,
-     "compression_ratio": "X:1",
-     "source_documents": ["{path1}", "{path2}"],
-     "completeness_check": "pass" or "pass_with_additions"
-   }
-   ```
-
-   Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
-
-6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
-
-### Stage 4: Round-Trip Validation (--validate only)
-
-This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
-
-1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
-
-   For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
-
-   **Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
-
-2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
-
-3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
-   - Is the core information present in the reconstruction?
-   - Are specific details preserved (numbers, names, decisions)?
-   - Are relationships and rationale intact?
-   - Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
-
-4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
-
-   ```markdown
-   ---
-   type: distillate-validation
-   distillate: "{distillate path}"
-   sources: ["{source paths}"]
-   created: "{date}"
-   ---
-
-   ## Validation Summary
-   - Status: PASS | PASS_WITH_WARNINGS | FAIL
-   - Information preserved: {percentage estimate}
-   - Gaps found: {count}
-   - Hallucinations detected: {count}
-
-   ## Gaps (information in originals but missing from reconstruction)
-   - {gap description} — Source: {which original}, Section: {where}
-
-   ## Hallucinations (information in reconstruction not traceable to originals)
-   - {hallucination description} — appears to fill gap in: {section}
-
-   ## Possible Gap Markers (flagged by reconstructor)
-   - {marker description}
-   ```
-
-5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
+1. **Validate inputs.** Required: `source_documents`. Optional: `downstream_consumer` (judges signal vs noise; if omitted, preserve everything), `token_budget` (triggers split when exceeded), `output_path` (default: adjacent to primary source with `-distillate.md` suffix), `--validate` flag (round-trip reconstruction test).
+2. **Stage 1 — Analyze.** Run `scripts/analyze_sources.py` on the source paths. Use its routing recommendation (`single` / `fan-out`) and grouping output. Do not read sources yourself.
+3. **Stage 2 — Compress.** Spawn `agents/distillate-compressor.md` subagent(s):
+   - **Single mode** (≤3 files, ≤15K tokens): one compressor.
+   - **Fan-out mode**: one compressor per group, then a merge compressor consuming the intermediate distillates (not originals).
+   - **Graceful degradation:** if subagent spawning is unavailable, perform the work directly using the same instructions.
+4. **Stage 3 — Verify & output.** Completeness check (every returned heading and named entity appears in the distillate; up to 2 targeted fix passes). Format check (bullets only, no prose, no repetition, `##` themes). Save with frontmatter (`type: rihal-distillate`, `sources`, `created`, `token_estimate`, `parts`). Split distillates when >5K tokens or `token_budget` exceeded — see [`references.md`](references.md) for the split format.
+5. **Stage 4 — Round-trip validate (only with `--validate`).** Spawn `agents/round-trip-reconstructor.md` with the distillate path only (no source access). Semantic-diff the reconstruction against the originals. Produce `<name>-validation-report.md` with status, gaps, and hallucinations. Up to 2 fix passes if gaps found. Adds significant token cost — only for high-stakes use.
 
 ## Output Format
 
-Structured JSON result:
+Structured JSON on every run:
+
 ```json
 {
   "status": "complete",
-  "distillate": "path/to/distillate.md",
-  "compression_ratio": "3.2:1",
+  "distillate": "path/to/file-distillate.md",
+  "section_distillates": ["path1", "path2"] or null,
   "source_total_tokens": 15000,
-  "distillate_total_tokens": 4688
+  "distillate_total_tokens": 4688,
+  "compression_ratio": "3.2:1",
+  "source_documents": ["path1", "path2"],
+  "completeness_check": "pass" | "pass_with_additions"
 }
 ```
 
-## Workflow
-
-1. Read the user request and extract key parameters.
-2. Execute the skill logic as described in the Overview.
-3. Return output in the format specified below.
+Token counts come from `scripts/analyze_sources.py`. Compression ratio is `source / distillate`.
 
 ## Examples
 
-### Happy path
-**User:** "distill ./docs/architecture.md ./docs/decisions.md"
-**Result:** Analyzes sources → single-mode compression → saves `architecture-distillate.md` → reports 3.2:1 ratio
+**Happy path** — `distill ./docs/architecture.md ./docs/decisions.md` → single-mode → saves `architecture-distillate.md` → reports `3.2:1`.
+
+**Edge case — large folder** — `distill ./docs/ --validate` → fan-out mode (multiple compressors) → merge pass → round-trip validation produces a validation report.
+
+**Negative — summarisation request** — "summarize this meeting" — distillation is lossless compression, not summarisation. Clarify the difference or route to a writing skill.
+
+## Memory Bank Hooks
 
-### Edge case
-**User:** "distill ./docs/ --validate"
-**Result:** Fan-out mode for large folder → merge pass → round-trip validation via reconstructor agent
+- **Reads:** the source documents passed in
+- **Writes:** the distillate file (or folder) at the specified or default path
+- **Note:** for Memory Bank-specific distillates, use `rcode-memory-distill` instead — it knows the Memory Bank source set.
 
-### Negative boundary
-**User:** "summarize this meeting"
-**Result:** Distillation is lossless compression, not summarization. If user wants a summary, clarify the difference or route to a writing skill
+## Detailed reference
 
-6. **Clean up** — delete the temporary reconstruction files after the report is generated.
+See [`references.md`](references.md) for: the split distillate folder format, the validation report template, frontmatter schema, and `--validate` flag semantics.

package/rihal/skills/core/rihal-distillator/references.md

@@ -0,0 +1,118 @@
+# Distillator — Detailed Reference
+
+Detailed formats and templates for [`SKILL.md`](SKILL.md).
+
+---
+
+## Frontmatter schema
+
+Every distillate file (single or split-index) has:
+
+```yaml
+---
+type: rihal-distillate
+sources:
+  - "{relative path to source 1}"
+  - "{relative path to source 2}"
+downstream_consumer: "{consumer or 'general'}"
+created: "{ISO date}"
+token_estimate: {approximate token count}
+parts: 1   # or N for split distillates
+---
+```
+
+Source paths are relative to the distillate's location.
+
+---
+
+## Single distillate format
+
+When `total_tokens ≤ 5000` and `token_budget` is not exceeded:
+
+- One file: `{base-name}-distillate.md`
+- Frontmatter as above with `parts: 1`
+- Body: `##` themes containing self-contained bullets — no prose paragraphs, no decorative formatting, no repetition
+
+---
+
+## Split distillate format
+
+When `total_tokens > 5000` OR `token_budget` requires splitting:
+
+```
+{base-name}-distillate/
+├── _index.md           # orientation, cross-cutting items, section manifest
+├── 01-{topic-slug}.md  # self-contained section
+├── 02-{topic-slug}.md
+└── 03-{topic-slug}.md
+```
+
+`_index.md` contains:
+- Frontmatter (sources relative to the folder; `parts: N`)
+- 3-5 bullet orientation: what was distilled, from what
+- Section manifest: each section's filename + 1-line description
+- Cross-cutting items that span multiple sections
+
+Each section file:
+- Self-contained — loadable independently
+- 1-line context header: `This section covers {topic}. Part N of M.`
+- Same bullet-only format
+
+---
+
+## Round-trip validation report template
+
+Saved adjacent to the distillate as `{base-name}-validation-report.md`:
+
+```markdown
+---
+type: distillate-validation
+distillate: "{distillate path}"
+sources: ["{source paths}"]
+created: "{ISO date}"
+---
+
+## Validation Summary
+- Status: PASS | PASS_WITH_WARNINGS | FAIL
+- Information preserved: {percentage estimate}
+- Gaps found: {count}
+- Hallucinations detected: {count}
+
+## Gaps (information in originals but missing from reconstruction)
+- {gap description} — Source: {which original}, Section: {where}
+
+## Hallucinations (information in reconstruction not traceable to originals)
+- {hallucination description} — appears to fill gap in: {section}
+
+## Possible Gap Markers (flagged by reconstructor)
+- {marker description}
+```
+
+---
+
+## Validation semantics
+
+- **PASS** — every fact, decision, constraint, and relationship survives the round trip.
+- **PASS_WITH_WARNINGS** — minor gaps that the reconstructor itself flagged ("possible gap markers").
+- **FAIL** — material gaps or hallucinations. Trigger up to 2 targeted fix passes on the distillate.
+
+If gaps remain after fix passes: surface them honestly in the report. Do not pad the distillate with regenerated content — that introduces hallucination.
+
+---
+
+## When to use `--validate`
+
+- Distillates feeding architecture / system-design workflows
+- Distillates of regulatory or compliance documents
+- Distillates produced for an external consumer (client deliverable)
+- Anywhere information loss is unacceptable
+
+Skip `--validate` for routine distillates (Memory Bank refresh, internal context loading) — it adds significant token cost.
+
+---
+
+## Cleanup behaviour
+
+- Intermediate distillates (fan-out mode) live only in memory; they are not saved.
+- Reconstruction files (`--validate` mode) are temporary; delete them after the validation report is written.
+- The validation report itself persists alongside the distillate.