# synapse

Adopt this skill: https://proskills.md/skills/other/yangjingo-synapse

Page: https://proskills.md/skills/other/yangjingo-synapse
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 8236
upstream: https://github.com/yangjingo/synapse/blob/HEAD/SKILL.md

````text
---
name: synapse
description: "Master skill for Why.J Engineering. Orchestrates forge → DSL → slides/blog HTML pipeline. Delegates to synapse-forge (ingestion), synapse-pretext (blog rendering), synapse-excalidraw (diagrams), and synapse-animation."
repository: https://github.com/yangjingo/Synapse
homepage: https://github.com/yangjingo/Synapse
version: 2.0.0
---

# Synapse

Master orchestrator for the Synapse skill system.

## Sub-Skills

| Skill | Directory | Purpose |
|-------|-----------|---------|
| `synapse-forge` | `skills/synapse-forge/` | URLs/files → DSL (熔炉): ingestion + synthesis |
| `synapse-design` | `skills/synapse-design/` | Content creation guidance (voice, structure, slides template) |
| `synapse-pretext` | `skills/synapse-pretext/` | Blog DSL → HTML rendering + text layout engine |
| `synapse-excalidraw` | `skills/synapse-excalidraw/` | Excalidraw diagram generation (Morandi palette, layout.js) |
| `synapse-animation` | `skills/synapse-animation/` | Animated SVG/GIF + Remotion output |

## Pipeline Overview

```
User provides URLs/files
        │
        ▼
  synapse-forge (Stage 1-3)
  Fetch → Extract → Synthesize
        │
        ▼
  DSL file (*.dsl.md)
       ╱ ╲
      ╱   ╲
     ▼     ▼
  Slides   Blog
  Render   Render
     │     │
     ▼     ▼
  HTML    HTML
```

## Operation A: Why.J Theater (Slides)

### Full Pipeline

1. **Ingest**: `synapse-forge` — URLs/files → Slides DSL
2. **Render**: copy `skills/synapse-design/references/WHYJ-SLIDES.html`, replace content per DSL
   - If target output has `examples/<project>/DESIGN.md`, load it first and treat it as a hard visual rule set.
   - For any new/recreated raster figure, **invoke the Codex built-in `$imagegen` skill and use its default built-in `image_gen` tool mode**.
   - Do not route figure generation through Gemini, Imagen APIs, Nano Banana, or another external image provider. If built-in `image_gen` is unavailable or fails, report the failure; use the `$imagegen` CLI/API fallback only after the user explicitly approves it.
   - Read both `Figure prompt suffix / 风格控制` and `文件落地` from DESIGN.md first, then merge into generated prompts.
   - For every `::visual`/prompt:
     - append or enforce：`white paper background`、`rough black ink`、`sparse labels`、`single accent #D97757`、`no gradients`、`no shadows`、`no 3D`、`no decorative clutter`、`no emoji`；
     - if prompt uses a different base palette, overwrite to align DESIGN.md（以 DESIGN.md 为准）；
     - all image assets must be written to `examples/<project>/figures/` and referenced as `./figures/...` in DSL/HTML.
3. **Post-process**: `npx prettier --write [file]`

### Structural Sequence

1. **00 / Cover** — Identity & Title (`YYYY/MM/DD`)
2. **01 / Context** — Factual survey: collect facts, pulse does high-level abstraction
3. **02 / Agenda** — Questions that grow from Context facts, guiding reader from different angles
4. **03-N / Mechanism** — Core sub-logics, one per slide, O(1) complexity
5. **Take A Ways** — Q→A mapping (Q1→A1...Q3→A3), Q4 becomes pulse conclusion
6. **Reference** — Verified source list

### Visual Rules

- **Cover**: NO image, NO pulse, NO pretext animation. Title + Chinese subtitle (topic thesis) + Version/Author/Date. Subtitle is NOT "Synapse vX.X".
- **Context (01)**: 事实 1-N list. H2 emphasizes "现状分析". Pulse does high-level abstraction. visual-box with Codex `$imagegen` prompt (single source of truth).
- **Agenda (02)**: Questions grow from Context facts. `push-left` + `fragment`. NO image, NO pulse.
- **Mechanism (03-N)**: pulse + visual-box + pretext animation. Codex `$imagegen` (Excalidraw-inspired: white paper background, rough black ink, sparse labels, single accent `#D97757`, no gradients, no shadows, no 3D, no decorative clutter). Raster generation uses the built-in `image_gen` path.
- **Take A Ways**: Q→A strict mapping. `push-left`, NO visual-box. Q4 → pulse with `fragment`.
- **Reference**: `.canvas-footer`. Bold title wraps `<a href>`, full URL inline. CSS `::before` auto-generates arrows — do NOT hand-write `→`.

### Rendering Rules

- **Watermark**: `whyj + {project_id} + YYYY/MM/DD`
- **HTML Title**: `{Project Name} | Synapse v{version}`
- **mark/strong**: both share `var(--strong-bg)`
- **DSL Directives**: `::math` → KaTeX, `::code` → `.code-container`, `::pulse` → `.pulse-layer`, `==text==` → `<mark>`
- **Pretext Animation**: all pages except Cover have `<div class="pretext-stage" data-pretext-src="slide">`
- **Design Source Override**: when `examples/<project>/DESIGN.md` exists, project visual controls and figure constraints from that file override the default template defaults (white paper, rough ink, sparse labels, `#D97757`, etc.).
  - Read any `Figure prompt suffix / 风格控制` section and append those constraints to every generated `::visual` prompt unless it conflicts with correctness.
  - Keep the source of truth in `examples/<project>/figures/index.md` (image name, prompt, usage, and placement).
  - Figure image assets for example outputs must remain under `examples/<project>/figures` and be referenced as `./figures/...` in DSL/HTML.
  - All figure insertion in HTML must point to this local path and allow prompt-only recovery when file is missing.
  - `::image`/`::visual` 默认只展示图像与 Caption，`prompt` 仅在放大/zoom 弹窗内展示。

### Copy-Not-Create (MANDATORY)

Slides HTML MUST be copied from verified template, never hand-written. Hand-writing misses ~100 lines CSS + ~200 lines JS (Reveal.js, pretext, fonts, colors).

## Operation B: Engineering Blog

### Full Pipeline

1. **Ingest**: `synapse-forge` — URLs/files → Blog DSL
2. **Render**: `synapse-pretext` — copy `skills/synapse-pretext/examples/dsv4-blog-layout.html`, fill DSL content
3. **Verify**: JS syntax check (no prettier — breaks ~2000-line inlined library)

### Blog Rendering Protocol (synapse-pretext)

1. `cp skills/synapse-pretext/examples/dsv4-blog-layout.html` to target
2. Replace: TITLE, LEAD, SECTIONS, PULSE, meta-tag, meta-date, `<title>`
3. Backtick template literals for ALL content strings (Chinese `""` breaks JS `"..."`)
4. bodyHTML uses single quotes (contains HTML tags)
5. Image paths: relative from output directory, prefer `./figures/...` under target example folder
6. DO NOT run prettier
7. Verify: `node -e "new Function(require('fs').readFileSync('file','utf8').match(/<script.*>([\s\S]*)<\/script>/)[1])"`
8. **Figure sync**: when DSL contains `Type: figure` sections, read reference template first (e.g. `dsv4-blog-opd-en.html`) and copy its complete figure pattern — independent section objects, prompts from slides DSL `::visual`, CSS `figure-prompt-vis`, zoom overlay prompt reveal logic.
   - Figure card keeps normal state clean (image + caption).
   - Prompt text stays in figure metadata and surfaces only when zoomed.
   - Figure section objects use `image: \`./figures/...\`` paths, and fallback prompt path remains recoverable if image file is missing.

### Blog Content Principles

- Senior-to-senior tone, zero marketing
- Thesis-first, mechanism-driven
- Follow `skills/synapse-forge/FORGE-DSL.md` Section C for voice and style

## Diagram Pipeline (excalidraw → animate → gif)

1. **Generate**: `synapse-excalidraw` builds `.excalidraw` with Morandi palette
2. **Validate**: collision check (`scripts/validate.js`)
3. **Upload**: `npx excalidraw-cli export <file>` → shareable URL → user confirms
4. **Animate**: `synapse-animation` handles output based on input type:
   - **Excalidraw** → excalidraw-animate (SVG/WebM/GIF)
   - **Direct GIF** → PIL/imageio primitives (Slack/Discord optimized)
   - **Remotion** → staged reveals for technical explainers
5. **Integrate**: embed in slides, blog, or deliver standalone

## Master Protocols (MANDATORY)

- DSL syntax → `skills/synapse-forge/FORGE.DSL.md` (唯一 DSL + 文风参考)
- Slides template → `skills/synapse-design/references/WHYJ-SLIDES.html`
- Blog template → `skills/synapse-pretext/examples/dsv4-blog-layout.html`
- Excalidraw diagrams → `skills/synapse-excalidraw/SKILL.md` (Phase 0 讨论
````

## File: README.md
upstream: https://github.com/yangjingo/synapse/blob/HEAD/README.md

````text
# Synapse

<div align="center">
  <img src="assets/logo.svg?v=2" alt="Synapse logic forge logo" width="144">

  **A logic forge for AI-native technical publishing.**

  [中文](README.zh-CN.md) · [Visual tour](docs/slides/index.html) · [Quickstart](docs/QUICKSTART.md)

  [![Release](https://img.shields.io/badge/release-v2.0.0-C45A20)](https://github.com/yangjingo/Synapse/releases/tag/v2.0.0)
  [![License: MIT](https://img.shields.io/badge/license-MIT-4A4338)](LICENSE.txt)
</div>

![Research notes, logs, and papers entering the Synapse logic forge and emerging as slides, an article, a diagram, and motion](docs/assets/readme/synapse-hero.png)

<div align="center"><sub>RAW EVIDENCE → LOGIC FORGE → ONE ARGUMENT SPINE → SLIDES · ARTICLE · DIAGRAM · MOTION</sub></div>

Synapse is a set of composable Codex Skills that turns URLs, files, and raw notes into traceable arguments and finished technical artifacts. Like the forge above, it compresses noisy inputs into one argument spine; that spine drives slides, engineering articles, diagrams, and motion—without leaving image prompts in the final output.

## Install

For a human-guided install:

```bash
npx --yes skills add https://github.com/yangjingo/Synapse \
  --agent codex --global --full-depth --copy
```

For an unattended agent install:

```bash
npx --yes skills add https://github.com/yangjingo/Synapse \
  --agent codex --global --full-depth --copy --skill "*" --yes
```

Restart Codex after installation. See the [Quickstart](docs/QUICKSTART.md) for verification and upgrade instructions.

## Use

```text
Use $synapse to turn these papers and notes into a Why.J-style slide deck
and engineering article. Keep every claim traceable and embed finished visuals.
```

The orchestrator delegates to five focused Skills:

| Skill | Job |
|---|---|
| `$synapse-forge` | Sources → verified argument DSL |
| `$synapse-design` | Narrative and slide composition |
| `$synapse-pretext` | Geometry-aware article rendering |
| `$synapse-excalidraw` | Editable technical diagrams |
| `$synapse-animation` | SVG, GIF, and Remotion motion |

## See the output

- [Visual introduction](docs/slides/index.html)
- [On-Policy Distillation](examples/opd/)
- [DeepSeek-V4](examples/deepseek-v4/)
- [CLI Revolution](examples/cli-revolution/)
- [Nano Claude Code](examples/nano-cc/)

## Develop

```bash
node scripts/refresh-skill-examples.js
node scripts/validate-slide-visuals.js
```

Contributor conventions are in [AGENTS.md](AGENTS.md).
````
