July 2026Level 7 · EmergenceWorlds & loops

cave-unicorn — Where It Fits

The last-mile organ that closes the gap between content the machine produces and readers the machine reaches.

The journey of this framework: the story

The system it lives in

cave-unicorn is the distribution layer of the SANCREV SDK — an L9 cave-auxiliary library (same layer law as cave-discord) that runs inside the CAVE runtime as CronAutomation organs. To understand where it sits, start with the full tower:

┌─────────────────────────────────────────────────────────────┐
    │  L0  LAMAI            — the acting whole: VEC chain + economy loop               │
    │  L1  NEXUS             — parks, Rangers, wizards, signup                         │
    │  L2  SANCREV OPERA     — the operated interface: spaces, ledger-room, iframes     │
    │                    ─── SOVEREIGNTY BOUNDARY (up = strings, down = commands) ───   │
    │  L3  WORLD             — Matrix engine + WOOM SDK                                 │
    │  L4  WORK SPINE        — GIINT/TK → missions → goldenize → GEAR → VEC facts     │
    │  L5  SUBSTRATE         — CartON · dragonbones · treeshell · SOMA · CB            │
    │  L6  HEAVEN            — agent framework (constitutes agents)                     │
    │  L7  CAVE              — agent runtime: HTTP services, organs, automations        │
    │  L8  CODING AGENT      — commodity slot: Claude Code / OM / opencode              │
    │  L9  SANCREV SDK       — libraries that build sancrev: cave-discord,              │
    │                           cave-unicorn (here), paia-builder, sanctum             │
    └─────────────────────────────────────────────────────────────┘
                        │
                        │  cave-unicorn's organs
                        │  (L9 library code) run as
                        ▼  CronAutomations on L7 CAVE Heart tick
                     ┌───────────────────────────────────────┐
                     │  GITHUB PAGES (aisaac site)          │
                     │  blog/ · frameworks.html · apply.html │
                     └───────────────────────────────────────┘
    

cave-unicorn is L9 code: it is a library that SANCREV coders use to build distribution functionality. Its three CronAutomation organs — fire_site_publish, fire_socials_pack, fire_socials_images — live inside L7 CAVE (the runtime that virtualizes the coding-agent slot), registered via the hot-reload automations dir the Heart tick reads. L7 consumes L9; cave-unicorn never imports CAVE back. The seam is cave_seam.py.

What flows through it

The pipeline is a three-stage organ chain, each firing on the nightly Heart tick, driven by property flags on CartON Wiki nodes:

02:00  Blog organ (cave.core.publishing.blog_organ_nightly)
           → produces Blog_Request {status: done, output_path: X.md}
                  ↓
    02:37  fire_site_publish  [unicorn_site_publish CronAutomation]
           → renders X.md → blog/{slug}.html  (post skeleton + markdown → HTML)
           → inserts an idempotent card into blog/index.html
           → git add / commit / (push if configured)
           → flips {site_published: true, site_url, site_published_at}
           → fires Discord announce (cave_discord)
                  ↓
    03:07  fire_socials_pack  [unicorn_socials_pack CronAutomation]
           → scans {site_published: true, no socials_packed yet}
           → FRAMEWORK-FIRST GATE: skips if sibling journey_core.json lacks deep_dive_url
           → dispatches heaven/MiniMax agent → fills journey_core.json + journey_blog.json
           → module enforces canonical core (overwrites agent-written JSON with authority)
           → deterministic render: twitter thread · LinkedIn post · Discord copy · image prompts
           → flips {socials_packed: true, socials_pack_path}
                  ↓
    03:37  fire_socials_images  [unicorn_socials_images CronAutomation]
           → reads {socials_packed: true, no images_rendered yet}
           → dispatches claude -p agent → excalidraw rendering of hero.png / social-share.png / thumbnail.png
           → verifies PNG artifacts exist
           → flips {images_rendered: true, images_dir}
                  ↓
           ready-to-post queue: {socials_queue}/{slug}/pack.md + images/
           (I post manually from the queue for now; direct Twitter/LinkedIn API posting is planned)
    

What arrives at cave-unicorn: Blog_Request nodes in CartON with status: done and an output_path pointing to a markdown file. The blog markdown contract: first # heading = title; first *...* paragraph = hook/subtitle; the rest is body.

What leaves cave-unicorn: A live HTML post on GitHub Pages ({site_base_url}/blog/{slug}.html), an updated blog index card with bumped count, a pushed git commit, a Discord announcement, a socials pack in the queue directory, and rendered PNG images — each stage updating the CartON node so the next stage knows what to pick up.

The never-raises contract: every fire_* function catches exceptions and writes them to the CartON node rather than raising. The Heart tick never crashes on a bad node.

What it unlocks

The last-mile is closed. Before cave-unicorn, the nightly blog organ wrote perfect markdown every night at 02:00 — and that was where the story ended. There was no path from the output directory to a live URL. Reaching sancovp.github.io/aisaac/blog meant manual HTML conversion, hand-editing the post skeleton, committing to GitHub, and pushing. Every single time.

Three things become possible now that the distribution pipeline exists:

The machine has an audience. Content that exists in the machine arrives at a reader screen every night without a human in the loop. The system can now say something and mean it — because someone might be listening. This changes what gets built, because now you know someone is watching.

The content organ and the business organ are the same machine. UNICORN is described in the CAVE architecture doc as "the business game of CAVE" — whether the business side works. The blog organ produces; cave-unicorn delivers; the socials organ amplifies. These are three views of one process, not three separate manual workflows.

The framework chapter pipeline gates correctly. The framework-first gate (_framework_ready) prevents the socials organ from packing a blog whose CTA/demo sections have no real links to point at. A journey whose sibling journey_core.json lacks deep_dive_url and plugin_url is held at the socials leg and retried the next night — once the chapter step has wired those links. The pipeline enforces its own completeness contract.

Run it inside your own system

cave-unicorn is the reference implementation of the distribution pipeline organ. Install it and wire it into your CAVE setup.

Install

pip install cave-unicorn
    

Or from source:

pip install --no-deps /path/to/cave-unicorn
    

The CLI verbs

# 0. Set up config (creates unicorn_config.json in the data dir)
    cave-unicorn init

    # View current config
    cave-unicorn show

    # Set a config value (JSON types accepted: true, 3, ["a","b"])
    cave-unicorn set push true

    # Publish one blog file directly (no CartON scan)
    cave-unicorn publish path/to/blog1.md --tags "tool-eng context-eng" --no-push

    # Rewrite internal links so chapter bundles point to live posts
    cave-unicorn publish path/to/blog2.md \
      --link "cave-unicorn-the-story.html=cave-unicorn-how-it-works-deep-dive.html"

    # List done-but-unpublished Blog_Request nodes
    cave-unicorn pending

    # Publish all pending blogs
    cave-unicorn publish-pending --push

    # Emit the CronAutomation schemas into the hot-reload dir (site + socials + images)
    cave-unicorn enable-automation --which all --push

    # Check what is waiting for socials
    cave-unicorn socials-pending

    # Generate socials packs (scan mode or direct)
    cave-unicorn pack-socials --md-path path/to/blog.md --live-url "https://..."

    # Render images for a pack
    cave-unicorn render-images --pack-path socials_queue/my-slug/
    

Config shape

The init command creates a config file with these keys:

{
      "site_root": "/path/to/aisaac-checkout",
      "blog_dir": "blog",
      "site_base_url": "https://sancovp.github.io/aisaac",
      "default_tags": ["framework"],
      "push": false,
      "remote": "origin",
      "branch": "main"
    }
    

The three organs as CronAutomations

When you run cave-unicorn enable-automation --which all, three schemas land in the hot-reload automations dir. CAVE's Heart tick reads them and fires each on its schedule:

Connect to your CAVE agent directly (programmatic)

from cave_unicorn import cave_seam

    # Register on a live CAVEAgent (the sancrev boot path)
    cave_seam.register_with_cave(cave_agent)

    # Or emit the schema straight to the hot-reload dir
    cave_seam.emit_schema()  # site publish
    cave_seam.emit_spec(cave_seam.build_socials_pack_automation())
    cave_seam.emit_spec(cave_seam.build_socials_images_automation())
    

cave-unicorn public repo: github.com/sancovp/cave-unicorn