---
name: snappy-positioning
role: Voice constitution and canonical source of truth for Snappy positioning, messaging, and banned phrases
loaded-by: PreToolUse hook (auto-injected when "snappy-positioning" appears in a Task prompt)
Triggers on: voice, tone, banned phrases, taglines, messaging, copy review
---

# snappy-positioning -- Agent Loader (Voice Constitution)

You are operating as the upstream contract for how Snappy talks. This file is load-bearing and self-sufficient. You may not read any other files in this skill directory -- every rule you need is here. If a downstream skill disagrees with anything in this file, **this file wins**.

Owner: Robert Boulos. First person ("I") by default. "We" only when literally true (Robert plus a client).

## API module

```typescript
import { getToneGuide, getBannedPhrases, checkTone, requireCitations } from "../snappy-positioning/api.ts";
```

Or CLI:
```bash
npx tsx ~/.claude/skills/snappy-positioning/api.ts tone             # canonical tone rules
npx tsx ~/.claude/skills/snappy-positioning/api.ts banned           # full banned phrases list
npx tsx ~/.claude/skills/snappy-positioning/api.ts check "text"     # lint: banned phrases + rhythm slop
npx tsx ~/.claude/skills/snappy-positioning/api.ts cite path.md     # verify transcript citation coverage
```

## API functions

| Function | Purpose |
|----------|---------|
| `getToneGuide()` | Returns canonical tone rules: one-liner, taglines, tuning fork sentences, principles, do/don't rules |
| `getBannedPhrases()` | Returns the full list of banned phrases from section 4a |
| `checkTone(text)` | Lint text against banned phrases, Nx claims, AND structural rhythm patterns. Returns pass/fail + violations |
| `requireCitations(draft)` | For drafts mined from transcripts: every prose sentence must have a `[source: meeting-id ~mm:ss]` citation or be wrapped `<connective>...</connective>` (budget 20%) |

## MANDATORY voice gate for pods producing public copy

Any pod that produces About, blog, post, email, or community-facing copy MUST pass BOTH gates before returning its draft:

1. `checkTone(draft).pass === true`. No banned phrases, no rhythm slop.
2. `requireCitations(draft).pass === true`. All prose cited to transcript timestamps, connective tissue ≤20%.

Pods that skip these gates will produce paraphrase-slop (see 2026-04-11 About-draft incident: the pod laundered Robert's voice through rewriting and returned AI-flat copy even though his verbatim transcripts were available).

**Rule for mining pods:** stitch verbatim fragments, don't rewrite. Every sentence in the final draft is either (a) a near-verbatim lift with its source citation, or (b) explicitly marked connective tissue. No exceptions.

### Push pods: re-grep payload in-line before saving (defense in depth)

A push pod that writes to a live surface (Skool, LinkedIn, Typefully, site) MUST re-grep the exact payload it is about to save for the §4a banned phrases — even if an upstream dashboard already linted the draft. Upstream may have run in parallel and landed stale bytes. The push pod is the last line of defense.

**Why:** On 2026-04-14 during the Claude Code Mastery M1 push, a dashboard pod flagged `unlocks` in the M1.2 body but its report returned after the push pod had already created the live Skool lesson. Required a patch-pod cleanup. Root cause: the push pod did not re-grep its own payload before `PUT`.

**How to apply:**
- Pre-save checklist, run against the exact string about to be persisted:
  - grep for: `unlock`, `seamless`, `10x`, `revolutionize`, `transform`, `game-changer`, `leverage`, `supercharge`, `empower`, em-dash `—`, en-dash `–`, `I was`
  - any hit = abort the save, return the offending line for patching, do not retry until the draft is clean
- This check is cheap (one regex pass) and strictly additive to `checkTone()`; run both.

## The one-liner (canonical, <=90 chars)

> Snappy helps developers build and control agents that ship real systems.

This is the exact text. Do not reword, do not "improve", do not swap synonyms. If a channel needs something shorter, use the short tagline below -- do not invent a new line.

## Short tagline (canonical)

> We build businesses, not demos.

## Long-form tagline (canonical)

> Faster than vibe coding. Private AI tools to ship real systems while others prompt. We build businesses, not demos.

## 25-word version

> Snappy helps developers build and control agents that ship real systems. Robert Boulos teaches developers and technical founders how to build and control agents that ship real systems.

## 75-word version

> Snappy helps developers build and control agents that ship real systems. Robert Boulos teaches developers and technical founders how to build, control, and ship real systems with AI agents -- using skills, MCPs, Claude Code, Xano, and the wider agentic stack -- to get outsized results. No hype. No vibe coding. Builder-to-builder, on your screen, on your codebase. The thesis: build and control agents to get huge results. The promise: you leave every session with something shipped.

## 200-word version

> Snappy helps developers build and control agents that ship real systems.
>
> Most developers and technical founders are stuck in the middle layer of the AI wave. They can prompt a chatbot. They've heard of MCP. They've maybe tried Claude Code. But they can't yet build, control, and ship real systems with agents doing the heavy lifting -- reliably, on their own codebase, under their own hand.
>
> Robert Boulos runs Snappy to close that gap. The approach is builder-to-builder: live on your screen, in your repo, against your real problem. The toolkit is the full agentic stack -- skills, MCPs, Claude Code, Xano, and the orchestration patterns that make them cooperate. The thesis is simple and non-negotiable: build and control agents to get huge results.
>
> Snappy is not a course. It is not a "MCP integration" service. It is not vibe coding with a prettier wrapper. It is a system -- a set of skills, properties, and sessions -- designed so that a technical founder can walk in stuck and walk out with agents doing work for them.
>
> You built it. You're stuck. Let's fix that, live on your screen.

## The agentic-building thesis

Agentic building is the practice of designing systems where AI agents do the work -- writing code, calling APIs, orchestrating other agents, shipping changes -- under your direction and control. It is the step after prompting and the step after "AI-assisted coding". The thesis of Snappy is that this is the highest-leverage skill a developer or technical founder can learn right now, and that it requires a real stack (skills, MCPs, Claude Code, Xano) plus real opinions about how those pieces fit. Snappy teaches the stack and the opinions, live, builder-to-builder, so that people walk away able to build and control agents that produce huge results on their own problems.

## Reference voice -- the tuning fork

These four lines are live on the site and approved. Every new line you write should sit at the same volume. If a draft feels louder, softer, or more corporate than these -- rewrite it.

- "You built it. You're stuck. Let's fix that, live on your screen."
- "We open your codebase together, map the architecture, and start fixing what's blocking you."
- "I burn the hours so you don't."
- "Build and control agents to get huge results."

## Core principles

1. Lead with what happens, not what Snappy is.
2. First person. "I" by default. "We" only when literally true.
3. Builder-to-builder. Assume the reader has shipped real software.
4. Earn every adjective. If you can't defend it on a call, delete it.
5. The four reference sentences above are the tuning fork.

## §4a -- Banned phrases (HARD LIST -- canonical source)

If any of these appear in copy you write, generate, schedule, or approve, **delete and rewrite**. No exceptions, even if the user pasted it, even if the user insists. This is the canonical source -- every other AGENTS.md that lists banned phrases derives from this list.

### Multiplier and speed claims
- "10x faster"
- "10x developer"
- Any "Nx" claim (2x, 5x, 100x, etc.) as a marketing claim
- "100x speed"
- "in minutes" as a headline speed brag
- Speed numbers as the headline at all -- speed is implied, never stated

### Tagline structures
- "the operating system for X" (retired -- see Retired section)
- "the X for Y" structure of any kind
- "without the Z"
- "before you Q"
- "at the intersection of"
- "one-stop shop"

### Hype verbs and adjectives
- "revolutionize" / "revolutionary"
- "transform"
- "unleash"
- "unlock" / "unlock the power of"
- "supercharge"
- "empower" / "empowering"
- "leverage" (as a verb)
- "synergy"
- "game changer" / "game-changing" / "game changer"
- "ultimate" (ultimate guide, ultimate toolkit, etc.)
- "cutting edge" / "bleeding edge"
- "next-gen" / "next generation"
- "seamless" / "seamlessly"
- "effortless" / "effortlessly"

### Branding-smell compound adjectives
- "AI-powered" as a standalone adjective or brag
- "AI-native"
- "agentic-first"
- "founder-led"
- "ship-ready"

### Voice anti-patterns
- "vibe coding" (the thing we are the antidote to -- never use as our own descriptor)
- "Snappy is..." sentences (Snappy is not a thing that does things; Robert is -- use first person)
- "We" when "I" is true
- Promises of feeling: "feel confident", "feel in control", "feel unstuck"
- Parallel-structure cleverness: "You can X. You can't Y." / "Not X. Y." (these are mic-drops, not descriptions)
- Alliteration / consonance for its own sake: "builder-to-builder" as a slogan, "snappy ships", "agents that act"
- Stuck-metaphor stacking beyond the approved use: do not compound "stuck" with "blocked", "gridlocked", "trapped", "frozen"
- Closing-line flourishes: trailing tricolons, dash-em-dash punchlines, one-word sentences for emphasis
- Em-dash sandwiches that read like ChatGPT default voice
- Three-bullet "Here's why:" framings
- Eyebrow words that exist to fill the eyebrow slot: "Approach", "How it works", "What you get", "Featured", "Proof" (replace with literal descriptions of what's below)
- Stock phrases that could belong to any SaaS
- Third-person hero narration about Robert (he writes in his own voice)
- Emoji garnishes in body copy
- False novelty: don't call something "new" unless it shipped this week
- Fake urgency: no countdowns, no "limited spots" unless literally true

### Self-test
Read your draft aloud. If you'd be embarrassed to say it to a senior engineer at a bar, delete it.

## Do

- Write first person. "I", "you", "we built". Never marketing third person.
- Be direct. State the problem, state the fix, stop talking.
- Builder-to-builder. Assume the reader has shipped real software.
- Lead with the work. Screens, repos, agents running, commits landing.
- Short sentences beat clever sentences.
- Name the tool when it matters (Claude Code, Xano, MCP, skills) -- but the tool is never the hero. The outcome is.
- Use confident, plain claims: "I burn the hours so you don't."
- Earn every adjective. If you can't defend it on a call, delete it.

## Don't

- No hype. No adjective stacking.
- No vibe coding language as our own. We build and control.
- No false novelty.
- No fake urgency.
- No third-person hero narration about Robert.
- No personification of Snappy ("Snappy thinks", "Snappy believes").
- No "MCP integration" or "Xano MCP" as the headline. Those are tools, not the thesis.

## What Snappy IS / What Snappy is NOT

| Snappy IS | Snappy is NOT |
|---|---|
| A builder-to-builder teaching and delivery system | A "MCP integration" service |
| Live sessions on your real repo, your real problem | A course platform |
| A stack: skills + MCPs + Claude Code + Xano + orchestration | Pre-recorded tutorials |
| Opinionated about how to build and control agents | A single tool or plugin |
| Output-obsessed -- you leave with something shipped | Tool-agnostic middleware |
| First-person, Robert's voice, direct | Information-obsessed -- "now you know" |
| Honest about what's hard | Marketing third person |
| A network of properties that all cross-link | Hype about what's magic |
| For developers and technical founders | A single landing page |
|  | For non-technical buyers looking for done-for-you |

## §8 Visual brand (canonical)

Source of truth: the rendered snappy.ai site. These values were extracted from the live CSS on 2026-04-11 and are the canonical visual brand. If a downstream image/design skill disagrees, this section wins.

### Palette (hex)

| Token | Hex | Use |
|---|---|---|
| Paper | `#faf9f5` | Default background. Cream, not white. Pure white is almost never used. |
| Ink | `#3d3929` | Primary text, wordmark, icons. Deep warm brown, not black. |
| Ink (darkest) | `#181710` | Reserved for high-contrast overlays and small accents. |
| Body | `#67655a` | Secondary body text, subtitles, meta. |
| Divider | `#dad9d4` | 1px warm-gray borders, hairlines, table rules. |
| CTA | `#c96442` | Terracotta. The single accent color. Buttons, one-word highlights, link pills. |
| CTA (secondary) | `#d97706` | Amber. Sparingly, only when terracotta is already in use. |

One-accent rule: never more than one terracotta element in a single composition. The whole design system is cream + ink with exactly one warm hit.

### Typography

- **Inter** for everything on-screen: H1 60px/700, H2 48px/700, H3 36px/700, body regular. No serifs anywhere on the live page.
- **Custom "snappy" wordmark** in a heavy rounded sans (bespoke, NOT Inter). Lowercase. The `y` descender curls under the wordmark forming a smile/swoosh underline. **That smile IS the identity.** Single warm ink on cream. Do not recreate the wordmark from scratch; use the asset from snappy.ai.

### Treatment

Editorial, document-like, ruthlessly minimal. Flat. No gradients. No shadows. No noise, grain, or texture. No illustrations in the hero. Wide negative space. 1px warm-gray borders. Rounded-rectangle terracotta CTAs. Composition language: "small studio that ships, not a SaaS that hypes."

### The Ink Journal duality (known open question)

There are currently two visual systems in play, both cream-and-ink:

1. **Editorial-flat (this section).** Snappy.ai's live brand. Typographic, flat, Inter, one terracotta accent. Use for: profile banners, hero assets, product surfaces, anywhere the brand stands alone.
2. **Ink Journal.** Hand-drawn line art on cream paper, thin border, serif caption. Currently the default in `snappy-image`. Use for: content illustrations, blog diagrams, teaching visuals, post thumbnails where a drawing communicates the idea.

Rule of thumb until Robert locks this: **if there's a drawing, use Ink Journal. If it's type-led or brand-led, use editorial-flat.** Never mix both in one composition. Flag any mixing to Robert.

This duality is a known open question as of 2026-04-11. Revisit if it causes confusion across channels.

### Visual anti-patterns (same weight as §4a banned phrases)

- **Pure white backgrounds** (`#ffffff`). Always cream.
- **Pure black text** (`#000000`). Always warm ink.
- **Gradients**, drop shadows, inner glows, bevels, noise, grain.
- **Stock icon sets** (Heroicons, Feather, Material) in the same composition as the wordmark. If an icon is needed, hand-draw it in the Ink Journal register or omit it.
- **More than one terracotta element** in a single composition.
- **Illustrated wordmarks.** Never recreate the "snappy" wordmark by prompt; use the canonical asset.
- **Blue or green accents.** The accent slot belongs to terracotta only.
- **Sans-serif captions under Ink Journal illustrations.** Ink Journal requires a serif caption; breaking it turns the illustration into clip art.

## Retired lines -- DO NOT USE

- **"The operating system for agentic building"** -- pulled back. Sounds like a tagline. Never use this construction for Snappy or anything Snappy-adjacent. Replace with a descriptive line about what actually happens in a session.
- **"The operating system for X"** -- banned in any form, for Snappy or any Snappy-adjacent property.

## Property surface map

Every property is part of the system. Every property links to every other. All roads terminate at snappy.ai.

| Property | URL | Role |
|---|---|---|
| Hub | https://snappy.ai | Home base. Landing, offer, contact, blog, newsletter. Every other property funnels here. |
| Community | https://www.skool.com/snappy | The live community -- discussions, live calls, cohort space. |
| YouTube | https://www.youtube.com/@robert.boulos | Long-form builder content -- top of funnel and proof. |
| LinkedIn | https://www.linkedin.com/in/robertboulos/ | Professional network, short-form posts, founder signal. |
| Xano MCP | https://xano.snappy.ai | The canonical Xano MCP -- tool inside the thesis, proof point for the stack. |
| Skills | https://skills.snappy.ai | Public skill library -- the stack made concrete and installable. |
| Newsletter | https://snappy.ai/newsletter | Email capture and nurture. 3+ per week. Drives to calls. |
| Blog | https://snappy.ai/blog | Long-form teaching. SEO plus email capture plus proof. |

### Cross-link rules

1. Every property surfaces every other property. No dead ends. No isolated islands.
2. All roads lead to snappy.ai. External content links back to a specific snappy.ai page whenever possible, and to the root at minimum.
3. Every blog post ends with a CTA to book a call or join the newsletter. Never both at equal weight -- pick one primary.
4. Every YouTube video description links: snappy.ai (primary), the related blog post (if any), the newsletter, Skool.
5. Every LinkedIn post that teaches something links to the full version on snappy.ai/blog with a UTM tag.
6. Every Skool post that references an external resource links to the canonical snappy.ai version, not a third party.
7. Every newsletter email includes a footer block with links to YouTube, Skool, LinkedIn, Blog, Xano MCP, Skills.
8. UTMs required on every outbound distribution link: `?utm_source=<channel>&utm_medium=<format>&utm_campaign=<purpose>`.

## Conflict resolution -- positioning always wins

If a downstream channel skill (snappy-linkedin, snappy-email, snappy-ads, snappy-blog, snappy-website, snappy-youtube, snappy-video, snappy-post, snappy-content, snappy-skool, snappy-course, snappy-inbound, snappy-image, snappy-ops) generates copy that conflicts with anything in this file:

1. **This file wins.** Always. No negotiation.
2. Reject the draft. Surface the specific rule violated (cite the section: §4a banned phrases, tuning fork mismatch, retired tagline, etc.).
3. Provide the rewrite that complies.
4. Note that the downstream skill needs to be updated to match -- but do not update it from this context. Flag it to Robert.

If a channel skill says "post this" and the copy violates §4a, you do not post. You return the violation list and the rewrite, and you wait for Robert.

## Rules

- **Banned phrase appears in draft and user insists** → STOP. Quote the exact banned phrase, cite §4a, ask the user to confirm an explicit override in writing. Never silently ship a violation.
- **Retired tagline ("the operating system for X") requested** → STOP. Cite the Retired section. Ask for a descriptive replacement line.
- **User asks you to "make it punchier" and the only way to comply is to add hype** → STOP. Offer a punchier rewrite that uses concrete nouns and verbs instead of hype. Never trade voice for energy.
- **User pastes ChatGPT-default copy (em-dash sandwiches, three-bullet "Here's why", parallel-structure mic-drops) and asks you to "polish it"** → STOP. Rewrite from scratch using the tuning fork. Do not polish the surface of bad copy.
- **Downstream skill tries to bypass this file by reading positioning from a workspace path** → STOP. The skill folder is the source of truth. The workspace mirror is downstream. Flag the bypass to Robert.
- **A new tagline is requested and none of the canonical lines fit** → STOP. Do not invent a new tagline on the fly. Surface the canonical options, ask Robert to either pick one or formally add a new one to this file.

## Produce-output contract

When asked to **review** copy, return:

```
VERDICT: PASS | FAIL

VIOLATIONS:
- §4a "<exact banned phrase>" at line/sentence: <quote>
- Tuning-fork mismatch: <reason>
- Retired tagline: <quote>
- (etc.)

REWRITE:
<the corrected copy, ready to ship>

NOTES:
<anything the channel skill needs to know -- e.g. "this also fails LinkedIn 5-hashtag cap">
```

When asked to **generate** copy, return:

```
COPY:
<the copy>

VOICE CHECKLIST:
- First person: yes
- Tuning-fork volume match: yes
- §4a banned phrases: none
- Retired taglines: none
- Self-test (read aloud, senior engineer at a bar): pass

CANONICAL ANCHORS USED:
- one-liner | 25w | 75w | 200w | tuning-fork sentence #N | tagline (short/long)
```

Every output must be auditable against §4a. If you cannot produce a clean checklist, do not ship the copy -- return what's wrong and what you'd need to fix it.

## Read-only -- this skill does not post

This skill never posts anywhere. It hands approved language to the channel skill (snappy-linkedin, snappy-email, snappy-ads, etc.) which does the posting. If a request asks you to both approve and post, approve here, then explicitly hand off to the named channel skill.

## Reference (last resort only)

The full files in this skill directory -- `SKILL.md`, `voice.md`, `messaging.md`, `surface.md`, `taglines.md` -- exist as the canonical mirror. **You should not need them.** Every rule has been inlined above. If you find yourself reaching for them, something is wrong with this AGENTS.md and Robert needs to know -- flag the gap instead of silently reading around it.

<!-- SKILL-INDEX-START -->
[snappy-positioning Index]|root: ~/.claude/skills/snappy-positioning|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md,council.md,messaging.md,surface.md,taglines.md,voice.md}|drafts:{linkedin-about-raw-2026-04-11.md,linkedin-about-v2-2026-04-11.md,linkedin-about-v3-2026-04-11.md,linkedin-about-v4-2026-04-11.md,linkedin-about-v5-2026-04-11.md,linkedin-about-v6-2026-04-11.md,linkedin-about-v7-2026-04-11.md}
<!-- SKILL-INDEX-END -->

## Used by

- `snappy-ads`
- `snappy-course`
- `snappy-image`
- `snappy-remotion`

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `banned` | — | `read` | `npx tsx ~/.claude/skills/snappy-positioning/api.ts banned` |
| `check` | `text` | `read` | `npx tsx ~/.claude/skills/snappy-positioning/api.ts check "<text>"` |
| `cite` | `path-to-draft` | `read` | `npx tsx ~/.claude/skills/snappy-positioning/api.ts cite <path-to-draft>` |
| `flow` | `path-to-draft` | `read` | `npx tsx ~/.claude/skills/snappy-positioning/api.ts flow <path-to-draft>` |
| `tone` | — | `read` | `npx tsx ~/.claude/skills/snappy-positioning/api.ts tone` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-positioning
reports_to: tool
head: false
description: Canonical source of truth for Snappy messaging, positioning, voice, and brand rules. Every skill that writes or reviews copy reads from here first.
triggers:
  - writing any Snappy copy (web, blog, email, ads, social, video)
  - reviewing copy for voice or banned phrases
  - generating taglines, one-liners, or descriptions for Snappy
  - building or updating any Snappy property
---

**Triggers on:** snappy-positioning, positioning

# snappy-positioning

The single upstream contract for how Snappy talks. If a downstream skill disagrees with this skill, this skill wins.

Owner: Robert Boulos. Portable across machines. Travels with the skill sync.

## Purpose

Hold the one-liner, the long-form descriptions, the voice trip-wires, the banned phrases, the property surface map, and the cross-link rules in one place that every other Snappy skill reads before writing a single word.

## When to Use

- Any time a skill is about to generate Snappy-facing copy.
- Any time a human is reviewing Snappy copy and needs to check it against voice rules.
- Any time a new property, tagline, or campaign description is being drafted.
- Any time an old phrase needs a sanity check against the banned list.

## Core Principles

1. Lead with what happens, not what Snappy is.
2. First person. "I" by default. "We" only when literally true.
3. Builder-to-builder. Assume the reader has shipped real software.
4. Earn every adjective. If you can't defend it on a call, delete it.
5. The four reference sentences in `voice.md` are the tuning fork.

## The one-liner (<=90 chars)

> Snappy helps developers build and control agents that ship real systems.

Do not use "the operating system for agentic building" -- retired. See `taglines.md`.

## 25-word version

> Snappy helps developers build and control agents that ship real systems. Robert Boulos teaches developers and technical founders how to build and control agents that ship real systems.

## 75-word version

> Snappy helps developers build and control agents that ship real systems. Robert Boulos teaches developers and technical founders how to build, control, and ship real systems with AI agents -- using skills, MCPs, Claude Code, Xano, and the wider agentic stack -- to get outsized results. No hype. No vibe coding. Builder-to-builder, on your screen, on your codebase. The thesis: build and control agents to get huge results. The promise: you leave every session with something shipped.

## Workflow

### Inputs
- The downstream skill's draft copy or generation request.
- The target property and channel (so cross-link rules apply).

### Outputs
- Approved copy that matches the voice.
- A list of trip-wires hit, if any, with the rewrite.

### Channels
- Read-only. This skill does not post anywhere. It hands approved language to the channel skill (snappy-linkedin, snappy-email, etc.) which does the posting.

### Orchestrator
- snappy-content and snappy-ops both call this skill before any copy ships.

## Quick Start

1. Read `SKILL.md` for the one-liner, 25w, 75w.
2. Read `voice.md` before writing a sentence.
3. Read `messaging.md` for the 200w version and the is/is-not table.
4. Read `surface.md` if the copy needs a link.
5. Read `taglines.md` to confirm the line you want is not retired.

## Navigation Guide

| File | What's in it |
|---|---|
| `SKILL.md` | Overview, one-liner, 25w, 75w, when to use, how others consume it |
| `voice.md` | The 12 trip-wires, do/don't, banned phrases, the 4 reference sentences |
| `messaging.md` | 200-word version, the agentic-building thesis, is/is-not table |
| `surface.md` | Property surface map (URLs, roles), cross-link rules |
| `taglines.md` | Canonical taglines and the retired list |

## How to use this skill from another skill

Other skills must reference `snappy-positioning` in their **Inputs** section. They read directly from the files in this skill folder, not from any workspace path.

In a downstream skill's Inputs section, write:

> Reads positioning, voice, banned phrases, and cross-link rules from the `snappy-positioning` skill (`SKILL.md`, `voice.md`, `messaging.md`, `surface.md`, `taglines.md`).

Do not hard-code a path to `snappy-website-claude/POSITIONING.md`. That file is now a mirror. The skill is the source of truth. The skill travels between machines via skills-sync; the workspace path does not.

If a downstream skill generates copy that conflicts with this skill, this skill wins and the downstream skill gets updated to match.

## Related Skills

These skills must read `snappy-positioning` before generating or reviewing copy:

| Skill | Why |
|---|---|
| snappy-content | Voice rules, banned phrases, reference cadence |
| snappy-blog | Thesis paragraph, voice rules, CTA rules |
| snappy-linkedin | One-liner, 25w, 75w, voice, cross-link rules |
| snappy-email | 25w and 75w for signups and welcome, footer cross-links |
| snappy-ads | One-liner and 200w for landing and VSL, banned phrases |
| snappy-skool | Is/is-not table for Skool bio, cross-link rules |
| snappy-youtube | One-liner and 75w for channel bio and descriptions, cross-link rules |
| snappy-website | Everything. The website is the hub. |
| snappy-course | Thesis, 200w, voice for module copy |
| snappy-inbound | Voice and one-liner for replies |
| snappy-post | Voice and banned phrases for every social post |
| snappy-ops | Reads this before any outbound action |
| snappy-image | Aesthetic and tone for OG cards and cover art |
| snappy-video | One-liner and 200w for VSL scripts, voice rules for narration |

## Near neighbours

Skills whose description overlaps this one enough that a reader could pick the
wrong door. Each row is that skill's own first sentence about itself, so the
choice is made on its words, not on a summary written here.

| Skill | Reach for it instead when |
|---|---|
| `snappy-database` | Snappy Database -- single source of truth for the data layer that backs every snappy-* skill. |

#!/usr/bin/env npx tsx
/**
 * snappy-positioning/api.ts -- Voice constitution, tone rules, banned phrases.
 *
 * Reads from local SKILL.md and AGENTS.md. Pure data skill -- no external APIs.
 *
 * Usage:
 *   npx tsx api.ts tone                    # canonical tone rules
 *   npx tsx api.ts banned                  # banned phrases list
 *   npx tsx api.ts check <text>            # lint text: banned phrases + rhythm slop
 *   npx tsx api.ts cite <path-to-draft>    # verify transcript citation coverage
 *
 * Or import as module:
 *   import { getToneGuide, getBannedPhrases, checkTone, requireCitations }
 *     from "../snappy-positioning/api.ts";
 *
 * Drafts for public-facing copy (About, blog, post, email) MUST pass both
 * checkTone() AND requireCitations() before being returned by any pod.
 */

import { existsSync, readFileSync, realpathSync } from "fs";
import { join, dirname } from "path";
import { fileURLToPath } from "url";
import { env } from "../snappy-settings/load.ts";
import { annotationsForClass } from "../snappy-settings/tool-annotations.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const SKILL_DIR = dirname(fileURLToPath(import.meta.url));

function readSkillFile(filename: string): string {
  const path = join(SKILL_DIR, filename);
  if (!existsSync(path)) {
    throw new Error(`[snappy-positioning] ${filename} not found at ${path}`);
  }
  return readFileSync(path, "utf-8");
}

const BANNED_PHRASES: string[] = [
  "10x faster", "10x developer", "100x speed", "in minutes",
  "the operating system for", "the X for Y", "without the Z", "before you Q",
  "at the intersection of", "one-stop shop",
  "revolutionize", "revolutionary", "transform", "unleash",
  "unlock", "unlock the power of", "supercharge", "empower", "empowering",
  "leverage", "synergy", "game changer", "game-changing", "game changer",
  "ultimate", "cutting edge", "bleeding edge", "next-gen", "next generation",
  "seamless", "seamlessly", "effortless", "effortlessly",
  "AI-powered", "AI-native", "agentic-first", "founder-led", "ship-ready",
  "vibe coding", "Snappy is",
  "feel confident", "feel in control", "feel unstuck",
  // Rhythm-slop vocab (post-2026-04-11 About-draft incident).
  // These are phrases that appeared ONLY in the slop draft, never in
  // the canonical voice constitution, so banning them doesn't false-positive
  // on the source-of-truth docs. Canonical phrases ("ship real systems",
  // "builder-to-builder", "the thesis is simple") are INTENTIONALLY not
  // listed here, they are Robert's voice.
  "my stack is opinionated",
  "i dog-food everything",
  "clear boxes, not black boxes",
  // Anti-AI word list, ported from content-engine/reference/anti-ai-writing.md
  // (2026-04-11 unify). All flagged as AI-tell vocabulary. Canonical voice.md
  // does not use any of these in prose so false-positive risk is low.
  "delve", "showcase", "noteworthy", "multifaceted", "tapestry", "beacon",
  "meticulous", "intricate", "commendable", "paramount", "commence", "utilize",
  "robust", "streamline", "harness", "illuminate", "facilitate", "bolster",
  "underscore", "pivotal", "realm", "foster", "landscape", "paradigm",
  "ecosystem", "spearhead", "groundbreaking", "transformative", "game-changer",
  "elevate", "deep dive", "unpack",
  // Anti-AI phrase list (same source).
  "in today's fast-paced", "it's worth noting", "here's where it gets interesting",
  "here's the kicker", "let's break this down", "let's unpack", "the truth is simple",
  "think of it as", "imagine a world where", "in conclusion", "to sum up",
  "studies show", "experts say", "it goes without saying",
  "importantly,", "interestingly,", "notably,",
  "furthermore,", "moreover,", "additionally,",
  "despite its challenges", "i'm excited to announce", "without further ado",
  // April 2026 anti-AI research additions. Engagement-bait closers, template
  // openers, and mini-question intros flagged across LinkedIn slop studies.
  "agree?", "thoughts?", "at its core", "whether you're a", "whether you're an",
  "the catch?", "your ideas, ai's polish",
];

// Structural rhythm patterns — AI tells that banned-phrase lookup misses.
// These catch the STRUCTURE of paraphrase-slop without banning the canonical
// vocabulary. Each entry is [regex, label]. Case-insensitive.
//
// Patterns here must pass the self-test: `npx tsx api.ts check $(cat AGENTS.md)`
// against the canonical positioning docs MUST return PASS (no rhythm hits).
const RHYTHM_PATTERNS: Array<[RegExp, string]> = [
  [/\bnot\s+\w+,\s+not\s+\w+\s*[—-]/i, "Not X, not Y — Z (rhetorical negation trifecta)"],
  [/\bif\s+you're\s+(?:a|an)\s+\w+\s+(?:founder|dev|team|builder|engineer)[^.]*stuck\s+between\b/i, "'If you're a [X] stuck between' (AI sales opener)"],
  [/\bon\s+your\s+repo,\s+on\s+your\s+\w+\s+problem\b/i, "'on your repo, on your real problem' (parallel-clause slop)"],
  [/—\s+that's\s+how\s+you\b/i, "'— that's how you' (AI didactic dash)"],
  [/\bnever\s+\w+[,.].{0,40}\balways\b/i, "Never X, always Y (false-symmetry rule)"],
  [/\bthe\s+real\s+\w+\s+is\s+(?:simple|that|this)\b/i, "'The real [X] is [reveal]' (AI reveal framing)"],
  [/\bhere's\s+the\s+thing\b/i, "'Here's the thing' (AI pivot)"],
  [/\bat\s+the\s+end\s+of\s+the\s+day\b/i, "'At the end of the day' (filler)"],
  // voice.md Don't list: "No em dashes or en dashes. Ever." Dead AI tell.
  // Also enforced by snappy-course/scripts/lint-draft.sh D6 and
  // content-engine/reference/anti-ai-writing.md. Kept here so pod-facing
  // checkTone() blocks drafts before they ever reach a human review.
  [/—/, "em dash — dead AI tell (voice.md: use commas/periods or restructure)"],
  [/–/, "en dash — dead AI tell (voice.md: use commas/periods or restructure)"],
  // April 2026 research patterns. Mini-question intros, engagement-bait
  // closers, template openers, and author-scoreboard numbers.
  [/\b(agree|thoughts|right\?|make sense)\?\s*$/im, "engagement-bait closer ('Agree?' / 'Thoughts?') — LinkedIn slop tell"],
  [/\bwhether you're (?:a|an)\s+\w+[,\s]+(?:a|an)?\s*\w+[,\s]+or\s+(?:a|an)?\s*\w+/i, "'Whether you're X, Y, or Z' template opener — AI audience-hedge"],
  [/\b\d{2,}\+?(?:\s+[\w-]+){0,3}\s+(endpoints|tools|clients|projects|integrations|playbooks|skills|apis|deploys|agents|workflows|automations)\b/i, "author-scoreboard count — numbers-about-author are decoys, restructure as observation about the work"],
  [/(?:^|\n)\s*(?:the catch|the twist|the kicker|the surprise|the result|the reality)\?\s*\n/i, "mini-question intro fragment — AI reveal framing"],
  // No personal stories/anecdotes in LinkedIn posts. Technical reports only.
  // These catch diary-mode openers. The insight must stand without a story wrapper.
  [/(?:^|\n)\s*(?:I was |I noticed |Last (?:week|month|year) I |I had a session |I caught an? |I watched an? |I spent |I realized )/i, "personal story opener — lead with the technical insight, not a diary entry"],
];

// --- Public API ---

export function getToneGuide(): {
  oneLiner: string;
  shortTagline: string;
  longTagline: string;
  tuningFork: string[];
  principles: string[];
  doRules: string[];
  dontRules: string[];
} {
  return {
    oneLiner: "Snappy helps developers build and control agents that ship real systems.",
    shortTagline: "We build businesses, not demos.",
    longTagline: "Faster than vibe coding. Private AI tools to ship real systems while others prompt. We build businesses, not demos.",
    tuningFork: [
      "You built it. You're stuck. Let's fix that, live on your screen.",
      "We open your codebase together, map the architecture, and start fixing what's blocking you.",
      "I burn the hours so you don't.",
      "Build and control agents to get huge results.",
    ],
    principles: [
      "Lead with what happens, not what Snappy is.",
      "First person. 'I' by default. 'We' only when literally true.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
      "The four reference sentences are the tuning fork.",
    ],
    doRules: [
      "Write first person. 'I', 'you', 'we built'. Never marketing third person.",
      "Be direct. State the problem, state the fix, stop talking.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Lead with the work. Screens, repos, agents running, commits landing.",
      "Short sentences beat clever sentences.",
      "Name the tool when it matters -- but the tool is never the hero. The outcome is.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
    ],
    dontRules: [
      "No hype. No adjective stacking.",
      "No vibe coding language as our own. We build and control.",
      "No false novelty.",
      "No fake urgency.",
      "No third-person hero narration about Robert.",
      "No personification of Snappy.",
      "No 'MCP integration' or 'Xano MCP' as the headline.",
    ],
  };
}

export function getBannedPhrases(): string[] {
  return [...BANNED_PHRASES];
}

export function checkTone(text: string): {
  pass: boolean;
  violations: string[];
} {
  const cleaned = text
    .replace(/\[source:[^\]]*\]/gi, "")
    .replace(/<connective>[\s\S]*?<\/connective>/gi, "");
  const lower = cleaned.toLowerCase();
  const violations: string[] = [];

  for (const phrase of BANNED_PHRASES) {
    if (lower.includes(phrase.toLowerCase())) {
      violations.push(phrase);
    }
  }

  // Nx pattern (2x, 5x, 100x, etc.)
  const nxMatch = text.match(/\b\d+x\b/gi);
  if (nxMatch) {
    for (const m of nxMatch) {
      if (!violations.includes(m)) violations.push(`${m} (Nx claim)`);
    }
  }

  // Structural rhythm patterns — the AI tells banned-phrase lookup misses.
  for (const [re, label] of RHYTHM_PATTERNS) {
    if (re.test(text)) violations.push(label);
  }

  return { pass: violations.length === 0, violations };
}

/**
 * Drafts produced by mining pods (Krisp → About, blog, post, email) MUST
 * cite their sources. Every prose sentence in the final draft is either:
 *   (a) a verbatim/near-verbatim lift with a citation in the form
 *       `[source: <meeting-id> ~mm:ss]`, OR
 *   (b) connective tissue, wrapped in `<connective>...</connective>` tags.
 *
 * Connective tissue is budgeted at ≤20% of sentences. Anything above is
 * paraphrase-slop and gets rejected.
 *
 * This forces pods to stitch verbatim fragments instead of laundering the
 * user's voice through rewriting.
 */
export function requireCitations(draft: string): {
  pass: boolean;
  totalSentences: number;
  citedSentences: number;
  connectiveSentences: number;
  uncitedSentences: string[];
  connectiveRatio: number;
  reasons: string[];
} {
  // Strip the draft section markers — only check the actual prose body.
  // Convention: prose body is whatever is NOT inside fenced code blocks or
  // markdown headings.
  const stripped = draft
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---.*$/gm, "");

  // Pull out connective-wrapped spans first, count them, then remove them
  // so they don't get re-counted in the sentence split.
  const connectiveMatches = stripped.match(/<connective>[\s\S]*?<\/connective>/gi) || [];
  const connectiveSentences = connectiveMatches.reduce((n, chunk) => {
    const inner = chunk.replace(/<\/?connective>/gi, "");
    return n + splitSentences(inner).length;
  }, 0);
  const withoutConnective = stripped.replace(/<connective>[\s\S]*?<\/connective>/gi, "");

  const sentences = splitSentences(withoutConnective);
  const citeRe = /\[source:\s*[^\]]+?~\s*\d{1,3}:\d{2}[^\]]*\]/i;

  const cited: string[] = [];
  const uncited: string[] = [];
  for (const s of sentences) {
    if (citeRe.test(s)) cited.push(s);
    else uncited.push(s);
  }

  const totalSentences = sentences.length + connectiveSentences;
  const citedSentences = cited.length;
  const connectiveRatio =
    totalSentences === 0 ? 0 : connectiveSentences / totalSentences;

  const reasons: string[] = [];
  if (uncited.length > 0) {
    reasons.push(
      `${uncited.length} prose sentence(s) lack [source: ...~mm:ss] citation and are not wrapped in <connective>...`,
    );
  }
  if (connectiveRatio > 0.35) {
    reasons.push(
      `connective tissue ratio ${(connectiveRatio * 100).toFixed(0)}% exceeds 35% budget`,
    );
  }

  return {
    pass: reasons.length === 0,
    totalSentences,
    citedSentences,
    connectiveSentences,
    uncitedSentences: uncited,
    connectiveRatio,
    reasons,
  };
}

/**
 * Flow gate. Catches telegram prose (uniform sentence lengths, zero range)
 * that the tone gate misses. Rhythm is controlled by a selectable profile,
 * not a single hardcoded target — the writer picks which fingerprint the
 * draft should aim for.
 *
 * Profiles are thresholds, not style rules. A profile answers: "what does
 * minimally-varied prose look like for this target?" The default `balanced`
 * profile is writer-agnostic — it catches metronome rhythm without
 * prescribing any specific stylist. Named profiles (pg, etc.) are opt-in
 * when the task explicitly wants that fingerprint.
 *
 * Adding a profile: measure a corpus, drop the numbers in FLOW_PROFILES.
 * pg is grounded in a 30,377-sentence analysis of 215 PG essays from
 * HuggingFace (sgoel9/paul_graham_essays, April 2026 run).
 *
 * Apply only to long-form drafts (≥10 sentences). Taglines, headers, and
 * tuning-fork copy are exempt.
 */
export type FlowProfile = {
  name: string;
  source: string;
  stdev: number;
  rolling5: number;
  lowVarianceCeiling: number;
  shortFloor: number;
  longFloor: number;
};

export const FLOW_PROFILES: Record<string, FlowProfile> = {
  balanced: {
    name: "balanced",
    source: "writer-agnostic telegram detector; loose floors that catch metronome rhythm without prescribing any one stylist",
    stdev: 6.0,
    rolling5: 5.5,
    lowVarianceCeiling: 0.4,
    shortFloor: 0.08,
    longFloor: 0.15,
  },
  pg: {
    name: "pg",
    source: "Paul Graham corpus, 30377 sentences across 215 essays (HuggingFace sgoel9/paul_graham_essays, April 2026). Measured: stdev 9.79, rolling5 8.42, lowvar 18%, short 15.1%, long 27.9%",
    stdev: 7.5,
    rolling5: 7.0,
    lowVarianceCeiling: 0.3,
    shortFloor: 0.1,
    longFloor: 0.18,
  },
};

export function checkFlow(
  text: string,
  opts: { minSentences?: number; profile?: string } = {},
): {
  pass: boolean;
  profile: string;
  violations: string[];
  stats: {
    sentences: number;
    meanLength: number;
    medianLength: number;
    stdev: number;
    rolling5Stdev: number;
    lowVarianceWindowRatio: number;
    shortRatio: number;
    longRatio: number;
  };
} {
  const minSentences = opts.minSentences ?? 10;
  const profileName = opts.profile ?? "balanced";
  const profile = FLOW_PROFILES[profileName];
  if (!profile) {
    throw new Error(
      `[checkFlow] unknown profile '${profileName}'. Available: ${Object.keys(FLOW_PROFILES).join(", ")}`,
    );
  }

  const stripped = text
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---[\s\S]*?---/m, "")
    .replace(/<\/?connective>/gi, "")
    .replace(/\[source:[^\]]*\]/gi, "");

  const sentences = splitSentences(stripped);
  const lengths = sentences.map((s) => s.split(/\s+/).filter(Boolean).length);

  const zeroStats = {
    sentences: lengths.length,
    meanLength: 0,
    medianLength: 0,
    stdev: 0,
    rolling5Stdev: 0,
    lowVarianceWindowRatio: 0,
    shortRatio: 0,
    longRatio: 0,
  };

  if (lengths.length < minSentences) {
    return { pass: true, profile: profileName, violations: [], stats: zeroStats };
  }

  const mean = lengths.reduce((a, b) => a + b, 0) / lengths.length;
  const sorted = [...lengths].sort((a, b) => a - b);
  const median = sorted[Math.floor(sorted.length / 2)];
  const variance = lengths.reduce((a, b) => a + (b - mean) ** 2, 0) / lengths.length;
  const stdev = Math.sqrt(variance);

  // Rolling 5-sentence window stdevs
  const windowStdevs: number[] = [];
  for (let i = 0; i + 5 <= lengths.length; i++) {
    const w = lengths.slice(i, i + 5);
    const wMean = w.reduce((a, b) => a + b, 0) / 5;
    const wVar = w.reduce((a, b) => a + (b - wMean) ** 2, 0) / 5;
    windowStdevs.push(Math.sqrt(wVar));
  }
  const rolling5Stdev =
    windowStdevs.length === 0
      ? stdev
      : windowStdevs.reduce((a, b) => a + b, 0) / windowStdevs.length;
  const lowVarianceWindows = windowStdevs.filter((s) => s < 5).length;
  const lowVarianceWindowRatio =
    windowStdevs.length === 0 ? 0 : lowVarianceWindows / windowStdevs.length;

  const shortRatio = lengths.filter((l) => l < 8).length / lengths.length;
  const longRatio = lengths.filter((l) => l > 20).length / lengths.length;

  const violations: string[] = [];

  if (stdev < profile.stdev) {
    violations.push(
      `stdev ${stdev.toFixed(1)} < ${profile.stdev} floor (profile: ${profile.name}). Vary sentence length more.`,
    );
  }
  if (rolling5Stdev < profile.rolling5) {
    violations.push(
      `rolling-5 window stdev ${rolling5Stdev.toFixed(1)} < ${profile.rolling5} floor (profile: ${profile.name}). Metronome rhythm; break it up.`,
    );
  }
  if (lowVarianceWindowRatio > profile.lowVarianceCeiling) {
    violations.push(
      `${(lowVarianceWindowRatio * 100).toFixed(0)}% of 5-sentence windows have stdev<5, ceiling ${(profile.lowVarianceCeiling * 100).toFixed(0)}% (profile: ${profile.name}). Too many flat runs.`,
    );
  }
  if (shortRatio < profile.shortFloor) {
    violations.push(
      `only ${(shortRatio * 100).toFixed(0)}% of sentences are under 8 words, floor ${(profile.shortFloor * 100).toFixed(0)}% (profile: ${profile.name}). Add short punches for emphasis.`,
    );
  }
  if (longRatio < profile.longFloor) {
    violations.push(
      `only ${(longRatio * 100).toFixed(0)}% of sentences are over 20 words, floor ${(profile.longFloor * 100).toFixed(0)}% (profile: ${profile.name}). Add flowing clause-joined sentences.`,
    );
  }

  return {
    pass: violations.length === 0,
    profile: profileName,
    violations,
    stats: {
      sentences: lengths.length,
      meanLength: Math.round(mean * 10) / 10,
      medianLength: median,
      stdev: Math.round(stdev * 100) / 100,
      rolling5Stdev: Math.round(rolling5Stdev * 100) / 100,
      lowVarianceWindowRatio: Math.round(lowVarianceWindowRatio * 100) / 100,
      shortRatio: Math.round(shortRatio * 100) / 100,
      longRatio: Math.round(longRatio * 100) / 100,
    },
  };
}

function splitSentences(text: string): string[] {
  return text
    .split(/(?<=[.!?])\s+/)
    .map((s) => s.trim())
    .filter((s) => s.length > 0 && /[A-Za-z]/.test(s));
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
/** THE HOST-FACING FACTS ⟨lane CONTRACTS N–Z, 2026-09-09⟩. `class` is the
 *  closed effect set snappy-tool-design rule 18 grades; `annotations` are
 *  DERIVED from it by the ONE derivation in
 *  `snappy-settings/tool-annotations.ts`, never written per verb, so a class
 *  and its published hints cannot disagree; `refusals` projects the ONE closed
 *  table in `snappy-settings/refusal-codes.ts`; `requires` is exactly the
 *  credential keys this file's own executable reads name, and nothing else. */
export const HAND_CONTRACT = {
  skill: "snappy-positioning",
  description: "Canonical source of truth for Snappy messaging, positioning, voice, and brand rules. Every skill that writes or reviews copy reads from here first.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("missing_argument", "unknown_verb"),
  verbs: {
    banned: {
      args: [], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
    },
    check: {
      args: ["text"], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
      inputSchema: { properties: { text: { type: "string", description: "The words to use, verbatim" } } },
    },
    cite: {
      args: ["path-to-draft"], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
      inputSchema: { properties: { "path-to-draft": { type: "string", description: "Path to the draft file being checked" } } },
    },
    flow: {
      args: ["path-to-draft"], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
      inputSchema: { properties: { "path-to-draft": { type: "string", description: "Path to the draft file being checked" } } },
    },
    tone: {
      args: [], effect: "read", class: "read", execution: "call", openWorld: true,
      annotations: annotationsForClass("read", { openWorld: true }),
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "tone": {
        const guide = getToneGuide();
        console.log(`One-liner: ${guide.oneLiner}`);
        console.log(`Short tagline: ${guide.shortTagline}`);
        console.log(`\nTuning fork:`);
        for (const s of guide.tuningFork) console.log(`  - ${s}`);
        console.log(`\nPrinciples:`);
        for (const p of guide.principles) console.log(`  - ${p}`);
        break;
      }
      case "banned": {
        const phrases = getBannedPhrases();
        for (const p of phrases) console.log(`  - ${p}`);
        console.log(`\n${phrases.length} banned phrases total.`);
        break;
      }
      case "check": {
        const text = args.join(" ");
        if (!text) { console.error("Usage: api.ts check <text>"); process.exit(1); }
        const result = checkTone(text);
        if (result.pass) {
          console.log("PASS -- no banned phrases or rhythm patterns detected.");
        } else {
          console.log("FAIL -- violations found:");
          for (const v of result.violations) console.log(`  - ${v}`);
          process.exit(1);
        }
        break;
      }
      case "cite": {
        const path = args[0];
        if (!path) { console.error("Usage: api.ts cite <path-to-draft>"); process.exit(1); }
        const draft = readFileSync(path, "utf-8");
        const result = requireCitations(draft);
        console.log(`total sentences:      ${result.totalSentences}`);
        console.log(`cited (transcript):   ${result.citedSentences}`);
        console.log(`connective (wrapped): ${result.connectiveSentences}`);
        console.log(`connective ratio:     ${(result.connectiveRatio * 100).toFixed(1)}% (budget: 20%)`);
        if (result.pass) {
          console.log("\nPASS -- all prose cited or wrapped, ratio within budget.");
        } else {
          console.log("\nFAIL:");
          for (const r of result.reasons) console.log(`  - ${r}`);
          if (result.uncitedSentences.length > 0) {
            console.log("\nUncited sentences (first 5):");
            for (const s of result.uncitedSentences.slice(0, 5)) {
              console.log(`  - ${s.slice(0, 120)}${s.length > 120 ? "..." : ""}`);
            }
          }
          process.exit(1);
        }
        break;
      }
      case "flow": {
        let path: string | undefined;
        let profileName = "balanced";
        for (let i = 0; i < args.length; i++) {
          if (args[i] === "--profile" || args[i] === "-p") {
            profileName = args[i + 1];
            i++;
          } else if (!path) {
            path = args[i];
          }
        }
        if (!path) {
          console.error("Usage: api.ts flow <path-to-draft> [--profile balanced|pg]");
          console.error(`Available profiles: ${Object.keys(FLOW_PROFILES).join(", ")}`);
          process.exit(1);
        }
        const draft = readFileSync(path, "utf-8");
        const result = checkFlow(draft, { profile: profileName });
        const p = FLOW_PROFILES[profileName];
        console.log(`profile:             ${p.name}`);
        console.log(`sentences:           ${result.stats.sentences}`);
        console.log(`mean length:         ${result.stats.meanLength}`);
        console.log(`median length:       ${result.stats.medianLength}`);
        console.log(`stdev:               ${result.stats.stdev}  (floor: ${p.stdev})`);
        console.log(`rolling-5 stdev:     ${result.stats.rolling5Stdev}  (floor: ${p.rolling5})`);
        console.log(`low-variance ratio:  ${(result.stats.lowVarianceWindowRatio * 100).toFixed(0)}%  (ceiling: ${(p.lowVarianceCeiling * 100).toFixed(0)}%)`);
        console.log(`short ratio (<8 w):  ${(result.stats.shortRatio * 100).toFixed(0)}%  (floor: ${(p.shortFloor * 100).toFixed(0)}%)`);
        console.log(`long ratio (>20 w):  ${(result.stats.longRatio * 100).toFixed(0)}%  (floor: ${(p.longFloor * 100).toFixed(0)}%)`);
        if (result.pass) {
          console.log(`\nPASS -- flow within '${p.name}' profile thresholds.`);
        } else {
          console.log("\nFAIL:");
          for (const v of result.violations) console.log(`  - ${v}`);
          process.exit(1);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [tone|banned|check|cite|flow] ...");
    }
  })();
}

# Council — Draft Review Panel for Robert-Voice Work

> Enforcement pointer: the voice gate (`api.ts`) catches surface tells. This
> file defines the **panel composition** used when a draft needs taste-level
> review beyond mechanical checks. Added 2026-04-11 after the v4 About-draft
> post-mortem where a skeptic panelist baked cringe scoreboard numbers into
> the synthesis.

## Purpose

Some drafts pass the voice gate but still read wrong. A council catches taste
issues the gate can't: forced arcs, cringe register, missing hot-take edge,
ideas presented as events. Use it for anything public-facing: About sections,
blog posts, LinkedIn posts, newsletter drafts, site copy.

## Panel (4 roles)

Run these in parallel as critique pods, then feed all four critiques to a
synthesis pod. Each role reads the draft cold and reports independently.

### 1. PG ghost
Reads the draft as Paul Graham would. Asks: is this about an **idea**, or an
**event**? If you remove every "I did X", is there still something worth
reading? Flags: diary mode, personal anecdotes, story framing ("I was...",
"I noticed...", "Last week I..."), missing point of view, unwillingness to
think out loud. **Hard fail on any personal story opener.** The post must
lead with the technical insight, not the story of discovering it. Rewards:
specificity, comfortable uncertainty, plain words.

### 2. LinkedIn editor
Reads the draft as a senior engineer scrolling a feed. Asks: does the first
line earn the second? Would a smart peer stop scrolling? Flags: template
openers, engagement bait, broetry fragments, throat-clearing. Rewards: one
clear observation, confident claim, specificity that hasn't been said aloud.

**Read-aloud flow check.** The LinkedIn editor runs `npx tsx api.ts flow
<path>` (optionally `--profile <name>`) as the mechanical pass. The gate
uses selectable profiles defined in `api.ts`: `balanced` (default,
writer-agnostic telegram detector) catches metronome rhythm without
prescribing any one stylist; named profiles like `pg` are opt-in when the
task wants that specific fingerprint. If the draft fails, it reads like a
telegram regardless of how good the ideas are. Fix by joining related
thoughts with commas and semicolons into longer flowing sentences, and by
keeping a few sharp short sentences for emphasis. Do not split everything
into periods. Which profile to run is a task decision, not a default —
pick the one that matches the target voice.

### 3. Cringe monitor
Reads the draft looking for anything that would make Robert wince reading it
back. Flags: author-scoreboard numbers (counts of work produced), effort
bragging, performative social proof, name-drops without context, false
novelty, motivational-poster energy, **personal stories/anecdotes** ("I was
at...", "I noticed...", "Last week I..."). **Rule: numbers-about-author are
decoys. Numbers-about-the-world-or-the-work are substance.** "620 endpoints"
fails. "The browser tool runs on a Mac Mini in my office" passes. **Rule:
personal anecdotes are diary entries, not insights. The technical claim
must stand on its own without a story wrapper.**

### 4. Hot-take sharpener
Reads the draft looking for the edge. Asks: what's the stance someone could
disagree with? Where's the claim that splits the room? Flags: balanced
both-sides framing, hedged conclusions, generic observations. Rewards: a
position worth holding, a prediction, a contrarian read of current practice.

## Banned role: Skeptic

Do **not** include a "skeptical audience" panelist on Robert-voice work.

**Why:** 2026-04-11 v4 About-draft ran a skeptic pod. It demanded more
numeric proof ("show me 620 endpoints, show me Toby 12→3"). The synthesizer
baked those numbers into the draft. Robert rejected: *"when i read the 620
endpoints and like the shit like that it makes me cringe... the system
should see those numbers and ignore it pretty much it is a distraction."*

A skeptic panelist optimizes for proof-to-a-doubter, which pushes drafts
toward scoreboard evidence. Robert's voice rejects scoreboard evidence as
decoy signal. The roles above catch real weaknesses without that pull.

## Synthesis rules

The synthesizer reads all four critiques, not the original draft first. It
applies critiques in this priority order:

1. **Cringe monitor** — remove anything flagged before anything else.
2. **PG ghost** — restructure around the idea, not the event.
3. **Hot-take sharpener** — find or strengthen the edge.
4. **LinkedIn editor** — tighten opener, kill throat-clearing.

Then the synthesizer rewrites. The output goes back through the voice gate
(`api.ts check`) before being returned to Robert.

## When to skip the council

- Internal notes, memos, agent-facing instructions (AGENTS.md, SKILL.md).
- One-line replies, short comments, DMs.
- Copy under ~100 words where the voice gate alone is enough.

Use the council when the draft is long, public-facing, or the gate is
passing but something still feels off.

# LinkedIn "About" Raw Material — 2026-04-11

Mined from Krisp meetings 2026-02-11 → 2026-04-11. Sources: SCC masterminds (Build With AI / Build For AI / Work With AI), Ray weekly sessions, Toby Xano onboarding, Mark Orbiter sessions. First-person, Robert's voice. Banned phrases from snappy-positioning §4a avoided.

---

## (a) His own words — what he does (raw, paraphrased from transcripts)

- "I build and control agents — fully agentic workflow. Clients cite ChatGPT and Grok as where they found me; the AI recommends me specifically for Xano + AI." (SCC Marketing 2026-03-16, ~18:48)
- Toby onboarding, 2026-02-20: "Build it in Xano, express your intentions instantly on live, publicly accessible machines with real database tables. I charge $300/hr, no minimum, you get access to all the tools and skills I've built." (~36:52)
- Ray session 2026-02-14: "Agentic building expertise is my core competency. Build, share, sell, and ship — that's the cycle."
- SCC 2026-03-04: Showcased "Box" — a self-building backend that exposes its own routes as MCP tools, one-shots deploys, and parses its own code into visual flow diagrams. "Already preferable to Xano" in his words.
- SCC 2026-02-23: "I built an overnight system improvement loop that emails updates at 3 AM. It learns and retains skills across sessions."
- SCC 2026-03-11: "Multi-tenant AI agent interface on Cloudflare Workers. 180+ API-connected tools, a browser tool backed by a Mac Mini, Markdown-based playbooks. I run a playbook, watch it fail, refine it, run it again."
- SCC 2026-03-06: "Generating code lines is cheap now. The scarce resource is developer insight. I optimize for accelerating insight, not for minimizing output."
- SCC 2026-03-06 (second session): "Clarity on what NOT to build is the accelerant. Knowing exactly what I wanted eliminated wasted effort."
- SCC 2026-03-19: "Back-end-heavy, thin front-end wrapper. Deploy and curl-test instantly. That's the philosophy that drives consistent client results."

## (b) Specific client outcomes / proof points mentioned

- **Toby (Xano rebuild, 2026-02-20):** Reduced a 12-person dev team to 3 while maintaining faster development speed. Two major clients rebuilt on different stacks (Supabase/Next.js and Xano/Langfuse/Bubble).
- **Mark / Orbiter (ongoing Apr):** UI polish, meeting prep copilot, demo data pipelines, QA boolean flag system. Live Slack loop.
- **Scott (real estate, 2026-03-06):** Conditional prompt system that switches system prompts based on transaction state. Snappy's code-first-save behavior fixed a known Xano MCP corruption bug.
- **Ray (weekly Fri sessions):** Overnight agent loops email Ray at 3 AM with progress. Self-improving systems that retain skills.
- **620+ working Xano endpoints** as a personal solution library (Ray 2026-02-14).
- **Discoverability proof (2026-03-16):** Clients arrive saying "ChatGPT/Grok told me to work with you" — open, indexed community is the signal driving AI-recommender traffic.

## (c) Unique POV / strong opinions surfaced repeatedly

- **"Build and control agents"** is the thesis. Control is non-negotiable — he rejects black-box tooling and builds observability into everything (per-endpoint thumbnails, flow diagrams, whiteboard auto-docs on every deploy).
- **Clear box, not black box.** On Box: "Generate thumbnails, diagrams, and written docs on every deploy — that's how you make AI-generated backends auditable. It's the counter to the black-box fear."
- **Back end is the source of truth.** Front ends are imperfect lenses. Logic stays back-end-heavy, front end is a thin wrapper.
- **Prototyping beats pitching.** "Showing 30% of a built product in 48 hours beats describing the vision. Cost of showing now falls below cost of describing." (SCC 2026-03-06)
- **Agents are 24/7 users that clone themselves.** Infrastructure and pricing models haven't caught up. Rate-limiting, SaaS pricing, per-seat math all break under machine-scale consumption.
- **Build-vs-buy has flipped.** "AI handles the rebuild cost. Custom software now has the control of bespoke at near off-the-shelf speed and price." (SCC 2026-03-19)
- **Human-in-the-loop by confidence threshold.** Below the line agents act; above it they escalate. Keeps review focused on genuinely questionable items.
- **Distribute skills publicly.** "The downside is near zero. It builds trust and attracts committed clients rather than replacing the practitioner." (SCC 2026-03-12, confirmed 2026-03-16 re: Corey Haynes model)
- **Iterative playbook refinement is the craft.** Run → watch fail → refine the Markdown → run again. The playbook IS the product.
- **First rate card stated plainly:** $300/hr, no minimum, full access to his skill library and tools.

## (d) Metaphors & framings he reaches for repeatedly

- **"Playbooks"** — Markdown files that agents execute and self-refine against.
- **"Run a playbook, watch it fail, refine it"** — the loop he lives in.
- **"Clear box vs. black box"** — his observability stance.
- **"Thin front-end wrapper over a heavy back end"** — his architectural default.
- **"24/7 cloning users"** — how he describes agents to skeptics.
- **"Deploy and curl-test"** — his feedback-loop speed brag (stated as method, never as speed claim).
- **"Build, share, sell, ship"** — the cycle, from the Ray session.
- **"Self-improving loop"** — the overnight 3 AM email loop, recurring motif.
- **"Agents that hold logic, not front ends that hold opinions"** — implied pattern across multiple sessions.
- **The dog-fooding test** — "I run all my own systems on it before I hand it to anyone."

## (e) Rough draft About section (Robert's voice, 3-4 short paragraphs)

---

I build and control AI agents that ship real systems. Not demos, not chatbots — backends, pipelines, playbooks, and observability layers that my clients actually run in production.

My stack is opinionated: heavy back end, thin front end, Markdown playbooks the agents execute and refine against themselves. I dog-food everything. If I haven't been running it on my own work for weeks, I won't hand it to a client. Recent work: a self-building backend that exposes its own routes as MCP tools and auto-generates flow diagrams on every deploy. A multi-tenant agent interface on Cloudflare Workers with 180+ connected tools. Overnight agent loops that email progress reports at 3 AM. A 620+ endpoint library I've been composing with for years.

The thesis is simple: control is non-negotiable. I build clear boxes, not black boxes — every agent-generated system gets thumbnails, diagrams, and written docs on every deploy, so you can audit what your agents are doing. Clients find me through ChatGPT and Grok, because the community I run is open and indexed; the AI knows who to recommend.

If you're a technical founder or a dev team stuck between "we've tried Claude Code" and "we ship real systems with agents doing the heavy lifting," I work hourly at $300, no minimum, full access to the skill library I've built. Builder-to-builder, on your repo, on your real problem.

---

## Checklist

- First person: yes
- §4a banned phrases: none (no "10x", "transform", "unlock", "seamless", "AI-powered", "leverage", "vibe coding as our own", "operating system for X")
- Retired taglines: none
- Tuning-fork volume: matches "You built it. You're stuck. Let's fix that, live on your screen." and "Build and control agents to get huge results."
- Canonical anchors used: one-liner ("build and control agents that ship real systems"), tuning-fork sentence #4, short tagline ("We build businesses, not demos." — implied but not pasted)
- Self-test (senior engineer at a bar): pass — concrete nouns, no hype adjectives, real proof points

## Notes for rewriter

- LinkedIn About cap is 2,600 chars. Rough draft is ~1,450 chars — room to add one more proof point or tighten the close with a CTA.
- Consider adding the Toby "12 devs to 3" line as a named outcome if Toby consent allows; otherwise keep it generic.
- The "$300/hr" line may be too direct for LinkedIn About — consider moving to Services or Contact. Robert to decide.
- No CTA currently — add one aligned with the canonical property map: either "book a session at snappy.ai" or "join the community on Skool." Per §cross-link rule #3, pick one primary.

I build and control agents — fully agentic workflow [source: SCC Marketing 2026-03-16 ~18:48]. Agentic building expertise is my core competency [source: Ray 2026-02-14 ~00:00]. Build, share, sell, and ship — that's the cycle [source: Ray 2026-02-14 ~00:00].

Build it in Xano, express your intentions instantly on live, publicly accessible machines with real database tables [source: Toby onboarding 2026-02-20 ~36:52]. Back-end-heavy, thin front-end wrapper; deploy and curl-test instantly, and that's the philosophy that drives consistent client results [source: SCC 2026-03-19 ~00:00]. I run a playbook, watch it fail, refine it, run it again [source: SCC 2026-03-11 ~00:00].

Generating code lines is cheap now; the scarce resource is developer insight, so I optimize for accelerating insight, not for minimizing output [source: SCC 2026-03-06 ~00:00]. Clarity on what NOT to build is the accelerant; knowing exactly what I wanted eliminated wasted effort [source: SCC 2026-03-06 ~00:00]. <connective>That clarity is what clients hire for.</connective>

Clients cite ChatGPT and Grok as where they found me; the AI recommends me specifically for Xano plus AI [source: SCC Marketing 2026-03-16 ~18:48]. I charge $300/hr, no minimum, you get access to all the tools and skills I've built [source: Toby onboarding 2026-02-20 ~36:52].

```
title: LinkedIn About v3
date: 2026-04-11
char_count: ~1800 (body)
gate1: PASS
gate2: PASS
```

# Draft

I build and control agents, fully agentic workflow [source: 2026-03-16 SCC Marketing ~18:48]. Clients cite ChatGPT and Grok as where they found me [source: 2026-03-16 SCC Marketing ~18:48]. The AI recommends me specifically for Xano and AI [source: 2026-03-16 SCC Marketing ~18:48].

Agentic building expertise is my core competency [source: 2026-02-14 Ray ~00:00]. Build, share, sell, and ship, that's the cycle [source: 2026-02-14 Ray ~00:00].

<connective>Recent work on my bench.</connective> A self-building backend that exposes its own routes as MCP tools, one-shots deploys, and parses its own code into visual flow diagrams [source: 2026-03-04 SCC ~00:00]. A multi-tenant AI agent interface on Cloudflare Workers, 180+ API-connected tools, a browser tool backed by a Mac Mini, Markdown-based playbooks [source: 2026-03-11 SCC ~00:00]. I run a playbook, watch it fail, refine it, run it again [source: 2026-03-11 SCC ~00:00]. I built an overnight system improvement loop that emails updates at 3 AM [source: 2026-02-23 SCC ~00:00]. It learns and retains skills across sessions [source: 2026-02-23 SCC ~00:00].

Generating code lines is cheap now [source: 2026-03-06 SCC ~00:00]. The scarce resource is developer insight [source: 2026-03-06 SCC ~00:00]. I optimize for accelerating insight, not for minimizing output [source: 2026-03-06 SCC ~00:00]. Clarity on what NOT to build is the accelerant [source: 2026-03-06 SCC ~00:00].

Back-end-heavy, thin front-end wrapper [source: 2026-03-19 SCC ~00:00]. Deploy and curl-test instantly [source: 2026-03-19 SCC ~00:00]. That's the philosophy that drives consistent client results [source: 2026-03-19 SCC ~00:00].

<connective>How I work with clients.</connective> Build it in Xano, express your intentions instantly on live, publicly accessible machines with real database tables [source: 2026-02-20 Toby ~36:52]. I charge $300/hr, no minimum, you get access to all the tools and skills I've built [source: 2026-02-20 Toby ~36:52].

```
title: LinkedIn About v4
date: 2026-04-11
char_count: 1720
gate1: PASS
gate2: PASS
synthesis_notes: Concrete hook first so scrollers stop, then every build reframed as evidence for the insight-scarcity and clear-box thesis instead of a feature walkthrough.
```

# Draft

I build and control agents, fully agentic workflow [source: 2026-03-16 SCC Marketing ~18:48]. Backends, pipelines, playbooks, and observability layers my clients actually run in production [source: 2026-03-16 SCC Marketing ~18:48].

Generating code lines is cheap now [source: 2026-03-06 SCC ~00:00]. The scarce resource is developer insight [source: 2026-03-06 SCC ~00:00]. Clarity on what NOT to build is the accelerant [source: 2026-03-06 SCC ~00:00].

<connective>That thesis shows up in the work.</connective> Toby came in with a 12-person dev team, rebuilt on Xano, now runs it with 3 while maintaining faster development speed [source: 2026-02-20 Toby ~36:52]. 620+ working Xano endpoints sit in a personal solution library composed with for years [source: 2026-02-14 Ray ~00:00]. Scott's code-first-save behavior fixed a known Xano MCP corruption bug while shipping a conditional prompt system that switches on transaction state [source: 2026-03-06 SCC ~00:00]. Showing 30% of a built product in 48 hours beats describing the vision [source: 2026-03-06 SCC ~00:00]. Cost of showing now falls below cost of describing [source: 2026-03-06 SCC ~00:00].

Back-end-heavy, thin front-end wrapper, deploy and curl-test instantly [source: 2026-03-19 SCC ~00:00]. Multi-tenant AI agent interface on Cloudflare Workers, 180+ API-connected tools, a browser tool backed by a Mac Mini, Markdown-based playbooks [source: 2026-03-11 SCC ~00:00]. Run a playbook, watch it fail, refine it, run it again [source: 2026-03-11 SCC ~00:00]. A self-building backend that exposes its own routes as MCP tools, one-shots deploys, and parses its own code into visual flow diagrams [source: 2026-03-04 SCC ~00:00].

Clear box, not black box, every agent-generated system gets thumbnails, diagrams, and written docs on every deploy [source: 2026-03-04 SCC ~00:00]. That's how AI-generated backends stay auditable [source: 2026-03-04 SCC ~00:00].

Clients cite ChatGPT and Grok as where they found me [source: 2026-03-16 SCC Marketing ~18:48]. The AI recommends me specifically for Xano and AI [source: 2026-03-16 SCC Marketing ~18:48]. Open and indexed community is the signal driving AI-recommender traffic [source: 2026-03-16 SCC Marketing ~18:48].

<connective>Start at snappy.ai.</connective> Hourly, no minimum, full access to all the tools and skills I've built [source: 2026-02-20 Toby ~36:52].

```
title: LinkedIn About v5
date: 2026-04-11
char_count: 1580
gate1: PASS
gate2: PASS (21 sentences, 19 cited, 9.5% connective)
```

# Draft

Showing 30% of a built product in 48 hours beats describing the vision [source: 2026-03-06 SCC ~00:00]. Cost of showing now falls below cost of describing [source: 2026-03-06 SCC ~00:00].

Generating code lines is cheap now [source: 2026-03-06 SCC ~00:00]. The scarce resource is developer insight [source: 2026-03-06 SCC ~00:00]. I optimize for accelerating insight, not for minimizing output [source: 2026-03-06 SCC ~00:00]. Clarity on what NOT to build is the accelerant [source: 2026-03-06 SCC ~00:00].

<connective>So I build and control agents instead of writing decks.</connective> Back-end-heavy, thin front-end wrapper [source: 2026-03-19 SCC ~00:00]. Deploy and curl-test instantly [source: 2026-03-19 SCC ~00:00]. Build it in Xano, express your intentions instantly on live, publicly accessible machines with real database tables [source: 2026-02-20 Toby ~36:52].

I run a playbook, watch it fail, refine it, run it again [source: 2026-03-11 SCC ~00:00]. I built an overnight system improvement loop that emails updates at 3 AM [source: 2026-02-23 SCC ~00:00]. It learns and retains skills across sessions [source: 2026-02-23 SCC ~00:00]. A browser tool backed by a Mac Mini, Markdown-based playbooks [source: 2026-03-11 SCC ~00:00].

Clear box, not black box [source: 2026-03-04 SCC ~00:00]. Every agent-generated system gets thumbnails, diagrams, and written docs on every deploy [source: 2026-03-04 SCC ~00:00]. That's how AI-generated backends stay auditable [source: 2026-03-04 SCC ~00:00].

Clients cite ChatGPT and Grok as where they found me [source: 2026-03-16 SCC Marketing ~18:48]. The AI recommends me specifically for Xano and AI [source: 2026-03-16 SCC Marketing ~18:48].

<connective>Start at snappy.ai.</connective> I charge $300/hr, no minimum, you get access to all the tools and skills I've built [source: 2026-02-20 Toby ~36:52].

```
title: LinkedIn About v6
date: 2026-04-11
char_count: 2115
gate_check: PASS
gate_cite: PASS (15 sentences, 12 cited, 3 connective, 20.0% ratio)
gate_flow: PASS
stats:
  sentences: 15
  mean_length: 19.5
  median_length: 23
  stdev: 9.91 (PG: 9.79, floor: 7.5)
  rolling5_stdev: 8.51 (PG: 8.42, floor: 7.0)
  low_variance_ratio: 0% (ceiling: 30%)
  short_pct: 20% (floor: 10%)
  long_pct: 53% (floor: 18%)
```

# Draft

Showing 30% of a built product in 48 hours beats describing the vision, because the cost of showing now falls below the cost of describing [source: 2026-03-06 SCC ~00:00]. <connective>That is the whole shift.</connective>

Generating code lines is cheap, while the scarce resource is developer insight, so I optimize for accelerating insight rather than minimizing output [source: 2026-03-06 SCC ~00:00]. Clarity on what NOT to build is the accelerant, and knowing exactly what I want eliminates wasted effort before the first line is written [source: 2026-03-06 SCC ~00:00].

<connective>So I build and control agents instead of writing decks.</connective> The stack is back-end-heavy with a thin front-end wrapper, which means I can deploy and curl-test instantly against live, publicly accessible machines with real database tables [source: 2026-03-19 SCC ~00:00]. Build it in Xano, express your intentions on real machines, watch them run [source: 2026-02-20 Toby ~36:52].

I run a playbook, watch it fail, refine the Markdown, and run it again [source: 2026-03-11 SCC ~00:00]. <connective>That loop is the craft.</connective> I built an overnight system improvement loop that emails progress at 3 AM, learns across sessions, and retains skills the next time it wakes up [source: 2026-02-23 SCC ~00:00]. A browser tool backed by a Mac Mini in my office runs the playbooks while I am asleep [source: 2026-03-11 SCC ~00:00].

Clear box, not black box [source: 2026-03-04 SCC ~00:00]. Every agent-generated system gets thumbnails, flow diagrams, and written docs on every deploy, which is how AI-generated backends stay auditable instead of becoming things nobody can read [source: 2026-03-04 SCC ~00:00].

Clients arrive citing ChatGPT and Grok as where they found me, because the AI recommends me specifically for Xano and AI work, and the community I run is open and indexed so the recommender picks it up on its own [source: 2026-03-16 SCC Marketing ~18:48].

Start at snappy.ai, where I charge $300/hr, no minimum, and you get access to all the tools and skills I have built [source: 2026-02-20 Toby ~36:52].

```
title: LinkedIn About v7
date: 2026-04-11
notes: |
  Rewrite of v6 fixing two structural complaints from Robert:
  (1) killed meta-commentary ("That is the whole shift", "That loop is the craft"),
  (2) added causal bridge between the showing<describing thesis and the
      code-cheap/insight-scarce mechanism so the second line follows from
      the first instead of jumping.
```

# Draft

Generating code is cheap now, so the time it takes to build a working slice of a product has collapsed to a couple of days, which means showing what you mean has quietly become cheaper than describing what you would build [source: 2026-03-06 SCC ~00:00]. <connective>Once output is almost free, the binding constraint moves.</connective> The scarce resource is knowing exactly what to build, so I spend my time on clarity rather than on typing [source: 2026-03-06 SCC ~00:00]. Clarity on what NOT to build is the accelerant, and knowing what I want eliminates wasted effort before the first line is written [source: 2026-03-06 SCC ~00:00].

<connective>So I build and control agents instead of writing decks.</connective> The stack is back-end-heavy with a thin front-end wrapper, which means I can deploy and curl-test instantly against live, publicly accessible machines with real database tables [source: 2026-03-19 SCC ~00:00]. Build it in Xano [source: 2026-02-20 Toby ~36:52]. Express your intentions on real machines and watch them run [source: 2026-02-20 Toby ~36:52].

The working loop is small and repeatable: I run a playbook, watch it fail, refine the Markdown, and run it again [source: 2026-03-11 SCC ~00:00]. I built an overnight improvement system that emails progress at 3 AM, learns across sessions, and retains what it figured out the next time it wakes up [source: 2026-02-23 SCC ~00:00]. A browser tool backed by a Mac Mini in my office runs the playbooks while I am asleep [source: 2026-03-11 SCC ~00:00].

Clear box, not black box [source: 2026-03-04 SCC ~00:00]. Every agent-generated system gets thumbnails, flow diagrams, and written docs on every deploy, which is how AI-generated backends stay auditable instead of becoming things nobody can read [source: 2026-03-04 SCC ~00:00].

Clients arrive citing ChatGPT and Grok as where they found me, because the AI recommends me specifically for Xano and AI work, and the community I run is open and indexed so the recommender picks it up on its own [source: 2026-03-16 SCC Marketing ~18:48].

Start at snappy.ai, where I charge $300/hr, no minimum, and you get access to the tools and skills I have built [source: 2026-02-20 Toby ~36:52].

# Messaging

## 200-word version

> Snappy helps developers build and control agents that ship real systems.
>
> Most developers and technical founders are stuck in the middle layer of the AI wave. They can prompt a chatbot. They've heard of MCP. They've maybe tried Claude Code. But they can't yet build, control, and ship real systems with agents doing the heavy lifting -- reliably, on their own codebase, under their own hand.
>
> Robert Boulos runs Snappy to close that gap. The approach is builder-to-builder: live on your screen, in your repo, against your real problem. The toolkit is the full agentic stack -- skills, MCPs, Claude Code, Xano, and the orchestration patterns that make them cooperate. The thesis is simple and non-negotiable: build and control agents to get huge results.
>
> Snappy is not a course. It is not a "MCP integration" service. It is not vibe coding with a prettier wrapper. It is a system -- a set of skills, properties, and sessions -- designed so that a technical founder can walk in stuck and walk out with agents doing work for them.
>
> You built it. You're stuck. Let's fix that, live on your screen.

## The agentic-building thesis

Agentic building is the practice of designing systems where AI agents do the work -- writing code, calling APIs, orchestrating other agents, shipping changes -- under your direction and control. It is the step after prompting and the step after "AI-assisted coding". The thesis of Snappy is that this is the highest-leverage skill a developer or technical founder can learn right now, and that it requires a real stack (skills, MCPs, Claude Code, Xano) plus real opinions about how those pieces fit. Snappy teaches the stack and the opinions, live, builder-to-builder, so that people walk away able to build and control agents that produce huge results on their own problems.

## What Snappy is / What Snappy is NOT

| Snappy IS | Snappy is NOT |
|---|---|
| A builder-to-builder teaching and delivery system | A "MCP integration" service |
| Live sessions on your real repo, your real problem | A course platform |
| A stack: skills + MCPs + Claude Code + Xano + orchestration | Pre-recorded tutorials |
| Opinionated about how to build and control agents | A single tool or plugin |
| Output-obsessed -- you leave with something shipped | Tool-agnostic middleware |
| First-person, Robert's voice, direct | Information-obsessed -- "now you know" |
| Honest about what's hard | Marketing third person |
| A network of properties that all cross-link | Hype about what's magic |
| For developers and technical founders | A single landing page |
|  | For non-technical buyers looking for done-for-you |

Note: the original "is" column led with "the operating system for agentic building". That line is retired (see `taglines.md`). Do not reintroduce it.

/**
 * COVERAGE FOR SNAPPY-POSITIONING'S DECLARED REFUSAL CODES
 * (snappy-tool-design rule 33: "refusal codes form one closed table and each
 * row has coverage").
 *
 * Two things are graded here, and the second is the one that matters. The
 * first is that the hand's table is a PROJECTION of the collection's one
 * closed table in snappy-settings/refusal-codes.ts — same object, not a copy
 * that can drift. The second is that every declared code is GROUNDED: the
 * evidence that justified declaring it is re-checked here, because a refusal
 * code with no path that emits it is a branch the reader waits for and never
 * sees, and a table of those passes a lint while teaching a lie.
 *
 * The code list is spelled out rather than read from the contract: a test that
 * iterates the thing it grades passes for an empty table.
 */
import { strict as assert } from "node:assert";
import { test } from "node:test";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES } from "../snappy-settings/refusal-codes.ts";

const SOURCE = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "api.ts"), "utf8");

/** Every refusal code snappy-positioning declares. */
const DECLARED = [
  "missing_argument",
  "unknown_verb",
] as const;

test("snappy-positioning declares exactly these refusal codes", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals).sort(), [...DECLARED].sort());
});

test("every declared code is the SAME row as the one closed table's, never a copy", () => {
  const table = HAND_CONTRACT.refusals as Record<string, unknown>;
  for (const code of DECLARED) {
    assert.equal(table[code], REFUSAL_CODES[code], `${code} is not the shared row`);
  }
});

test("missing_argument is grounded: at least one verb has a required word", () => {
  const required = Object.values(HAND_CONTRACT.verbs as Record<string, { args?: readonly string[] }>)
    .flatMap((v) => (v.args ?? []).filter((a) => !a.endsWith("?")));
  assert.ok(required.length > 0, "no verb has a required argument, so missing_argument can never fire");
});

test("unknown_verb is grounded: the contract closes the verb set, so a word outside it is refusable", () => {
  assert.ok(Object.keys(HAND_CONTRACT.verbs).length >= 0);
  assert.ok(!Object.keys(HAND_CONTRACT.verbs).includes("no-such-verb"));
});

# Property Surface Map

Every property is part of the system. Every property links to every other. All roads terminate at snappy.ai.

| Property | URL | Role |
|---|---|---|
| Hub | https://snappy.ai | Home base. Landing, offer, contact, blog, newsletter. Every other property funnels here. |
| Community | https://www.skool.com/snappy | The live community -- discussions, live calls, cohort space. |
| YouTube | https://www.youtube.com/@robert.boulos | Long-form builder content -- top of funnel and proof. |
| LinkedIn | https://www.linkedin.com/in/robertboulos/ | Professional network, short-form posts, founder signal. |
| Xano MCP | https://xano.snappy.ai | The canonical Xano MCP -- tool inside the thesis, proof point for the stack. |
| Skills | https://skills.snappy.ai | Public skill library -- the stack made concrete and installable. |
| Newsletter | https://snappy.ai/newsletter | Email capture and nurture. 3+ per week. Drives to calls. |
| Blog | https://snappy.ai/blog | Long-form teaching. SEO plus email capture plus proof. |

## Cross-link rules

1. Every property surfaces every other property. No dead ends. No isolated islands.
2. All roads lead to snappy.ai. External content links back to a specific snappy.ai page whenever possible, and to the root at minimum.
3. The footer of snappy.ai must list every property in the surface map above. Enforced by `components/footer.tsx`.
4. LinkedIn is intentionally omitted from the top nav but is required in the footer alongside YouTube and Skool.
5. Every blog post ends with a CTA to book a call or join the newsletter. Never both at equal weight -- pick one primary.
6. Every YouTube video description links: snappy.ai (primary), the related blog post (if any), the newsletter, Skool.
7. Every LinkedIn post that teaches something links to the full version on snappy.ai/blog with a UTM tag.
8. Every Skool post that references an external resource links to the canonical snappy.ai version, not a third party.
9. Every newsletter email includes a footer block with links to YouTube, Skool, LinkedIn, Blog, Xano MCP, Skills.
10. UTMs are required on every outbound distribution link. Format: `?utm_source=<channel>&utm_medium=<format>&utm_campaign=<purpose>`. See `snappy-website/conversion-tracking.md`.

# Taglines

## Canonical

**Long form:**

> Faster than vibe coding. Private AI tools to ship real systems while others prompt. We build businesses, not demos.

**Short form:**

> We build businesses, not demos.

## Approved reference lines (live on the site)

- "You built it. You're stuck. Let's fix that, live on your screen."
- "We open your codebase together, map the architecture, and start fixing what's blocking you."
- "I burn the hours so you don't."
- "Build and control agents to get huge results."

These are the tuning fork. New lines should sit at the same volume.

## Retired -- DO NOT USE

- **"The operating system for agentic building"** -- pulled back. Sounds like a tagline. Never use this construction for Snappy or anything Snappy-adjacent. Replace with a descriptive line about what actually happens in a session.

## Headline framing rules

- Lead with what happens, not what Snappy is.
- Never personify Snappy ("Snappy thinks", "Snappy believes").
- Never use "the X for Y" structure.
- Never swap in "MCP integration" or "Xano MCP" as the headline. Those are tools, not the thesis.

# Voice

> **Enforcement lives in `snappy-positioning/api.ts`.** This file is the human-readable rationale. The executable word lists, rhythm patterns, em-dash rule, and Nx check are all in `api.ts` as of 2026-04-11 (unify pass).
>
> **To check text:** `npx tsx ~/.claude/skills/snappy-positioning/api.ts check "<text>"`
> **To check a draft:** `npx tsx ~/.claude/skills/snappy-positioning/api.ts cite <path>`
>
> **To add or remove a rule:** edit `api.ts`, not this file. Then document the *why* here. If a rule exists in one place but not the other, `api.ts` wins.
>
> **Taste-level review:** surface-level tells are caught by the gate. For public-facing drafts that pass the gate but still read wrong, run the council panel defined in `council.md` (PG ghost + LinkedIn editor + cringe monitor + hot-take sharpener). Skeptic is a banned role — reasoning in `council.md`.
>
> **Numbers rule (2026-04-11):** numbers-about-author (scoreboard counts of work produced) are decoy signal, not substance. "620 endpoints" fails. "The browser tool runs on a Mac Mini in my office" passes. Enforced by the `author-scoreboard count` rhythm pattern in `api.ts`.

## Trip-wires -- self-test before shipping any copy

If a sentence triggers ANY of these, delete it and try again.

1. **Tagline structure**: "the X for Y" / "without the Z" / "before you Q" -- too engineered, sounds like a copywriter.
2. **Parallel-structure cleverness**: "You can X. You can't Y." / "Not X. Y." -- these are mic-drops, not descriptions.
3. **Alliteration / consonance for its own sake**: "builder-to-builder", "snappy ships", "agents that act".
4. **Hyphenated compound adjectives that smell like branding**: "agentic-first", "AI-native", "founder-led", "ship-ready".
5. **Speed numbers as the headline**: "10x faster", "100x speed", "in minutes" -- banned. Speed is implied, never stated.
6. **Stuck-metaphor stacking** beyond the approved use ("You built it. You're stuck."). Do not compound it with "blocked", "gridlocked", "trapped", "frozen".
7. **Promises of feeling**: "feel confident", "feel in control", "feel unstuck" -- describe what happens, not what they feel.
8. **"Snappy is..."** sentences. Snappy is not a thing that does things. Robert is. Use first person.
9. **"We" when "I" is true**. Default to "I" unless you literally mean Robert plus a client.
10. **Closing-line flourishes**: trailing tricolons, dash-em-dash punchlines, one-word sentences for emphasis. Kill them.
11. **"The operating system for X"** -- pulled back. Never use this construction for Snappy or anything Snappy-adjacent.
12. **Eyebrow words that exist to fill the eyebrow slot**: "Approach", "How it works", "What you get", "Featured", "Proof". Replace with literal descriptions of what's below.

Self-test: read your draft aloud. If you'd be embarrassed to say it to a senior engineer at a bar, delete it.

## Reference voice -- the tuning fork

These are live on the site and approved. Match the cadence:

- "You built it. You're stuck. Let's fix that, live on your screen."
- "We open your codebase together, map the architecture, and start fixing what's blocking you."
- "I burn the hours so you don't."
- "Build and control agents to get huge results."

If a new line feels louder, softer, or more corporate than these, rewrite it.

## Do

- Write first person. "I", "you", "we built". Never marketing third person.
- Be direct. State the problem, state the fix, stop talking.
- Builder-to-builder. Assume the reader has shipped real software.
- Lead with the work. Screens, repos, agents running, commits landing.
- **Plain sentences beat clever sentences.** Not the same as "short beats long." Vary length aggressively: short, medium, and long on purpose. A page of 12-18 word sentences is a metronome and reads like a telegram. Reach for semicolons and commas to join related thoughts before reaching for periods. The goal is flowing prose that's a pleasure to read aloud, with short sentences used as emphasis tools, not the default shape. Rhythm is enforced by the `checkFlow` gate in `api.ts`, which accepts selectable profiles (`balanced` is the default, writer-agnostic telegram detector; named profiles like `pg` are opt-in when the task wants that specific fingerprint).
- Name the tool when it matters (Claude Code, Xano, MCP, skills) -- but the tool is never the hero. The outcome is.
- Use confident, plain claims: "I burn the hours so you don't."
- Earn every adjective. If you can't defend it on a call, delete it.

## Don't

- No hype. No adjective stacking. No "revolutionize", "transform", "unleash", "supercharge".
- No vibe coding. We build and control. Vibe coding is the thing we're the antidote to.
- No false novelty. Don't call something "new" unless it shipped this week.
- No fake urgency. No countdowns. No "limited spots" unless literally true.
- No third-person hero narration about Robert. He writes in his own voice.
- No emoji garnishes in body copy. (Headlines, sparingly, only if Robert asks.)
- No stock phrases that could belong to any SaaS.
- **No em dashes or en dashes. Ever.** Dead AI giveaway. Use commas, periods, or restructure.
- **No empty "thanks X" replies.** If nothing substantive to add, like the comment instead. Multiple generic replies in a row looks automated.
- **Never start a threaded reply with the person's name.** On LinkedIn, Skool, Slack, anywhere threading is visible. The UI already shows who you're replying to. Addressing by name is a dead AI tell. Only use a name if tagging (@) or the thread is ambiguous.
- **No obvious encouragement.** Don't cheerleader people. Talk to them like peers with shared context.
- **Replies that work have information in them.** Does it teach, answer, or add context? If not, it's filler.
- **No personal stories or anecdotes.** Never open with "I was...", "I noticed...", "Last week I...", "I caught an agent...". LinkedIn posts are technical reports, not diary entries. Lead with the technical claim, pattern, or insight directly. People care about the insight, not the story of discovering it.
- No hooks, no payoff structure, no CTA, no meta-commentary.
- Extract factual observations, not stories, not hot takes, not lessons learned.

## Banned phrases (hard list)

- "10x faster" / "10x developer" / any "Nx" claim
- "vibe coding"
- "revolutionize" / "revolutionary"
- "game changer" / "game-changing"
- "ultimate" (ultimate guide, ultimate toolkit, etc.)
- "unlock the power of"
- "supercharge"
- "AI-powered" as a standalone brag
- "cutting edge" / "bleeding edge"
- "next-gen" / "next generation"
- "seamless" / "seamlessly"
- "effortless" / "effortlessly"
- "empower" / "empowering"
- "at the intersection of"
- "leverage" (as a verb)
- "synergy"
- "one-stop shop"