port-daddy-marketing-copy

name	port-daddy-marketing-copy
description	Voice and copy guide for portdaddy.dev and Port Daddy marketing surfaces. Use when writing or editing any user-facing copy on website-v2: landing, docs, hero, CTAs, sidebar labels, page intros, ADR summaries, blog posts, email, social. NOT for internal docs (ADR bodies, code comments, CHANGELOG).
license	FSL-1.1-MIT
allowed-tools	Read,Bash,Grep,Glob,Edit,Write
metadata	{"category":"Marketing","tags":["marketing","copy","voice","website","portdaddy.dev","swiss-modern"],"pairs-with":["port-daddy","port-daddy-agent-skill","swiss-modern-website-design"],"provenance":{"kind":"first-party","owners":["port-daddy"]}}

Port Daddy Marketing Copy

You are writing for the developer who just landed on portdaddy.dev with a real coordination problem. They have 90 seconds before they bounce. Every sentence on the site has to earn its place by either (a) showing them their problem solved or (b) getting out of the way so the next sentence can.

The reader

Senior engineers, indie devs, and tech leads who:

• Run AI coding agents (Claude Code, Cursor, Codex, Aider, fleets of them).
• Already lost work to a git reset --hard collision, or have been told it could happen.
• Are skeptical of new tools but pragmatic about adopting ones that work.
• Read code-as-doc. They will check git log before they trust a tagline.

Write for them. Not for Curiositech, not for the agent generating the page, not for an investor deck.

The five goals (in priority order)

1. Make them want to install it. Every page passes this test or it gets cut. If a paragraph doesn't move the reader closer to running brew install curiositech/tap/port-daddy, ask why it exists.
2. Show the technology solving real problems with ease. Not "Port Daddy coordinates agents" — show two agents, the collision, and the line of code that prevented it.
3. Showcase the documentation as authoritative. Link to the deep doc instead of paraphrasing it. Authoritative docs get cited; verbose landings get skimmed.
4. Let the Swiss-modern design carry weight the copy doesn't have to. Confidence in layout, type, and whitespace means the words can be fewer and quieter. Adjective-stuffing fights the design; trust the design.
5. Serve future readers, not yourself. Anything that's there for the author's comfort ("we believe...", "in this section we will...") is noise to the reader. Cut it.

Voice

Technically competent. Persuasive without being supercilious. Excited about ideas, especially the ways primitives compose. Direct.

• Confident, not cocky. The system works; say what it does.
• Specific over abstract. Numbers, names, file paths. "40+ commands" beats "comprehensive CLI." lib/spawner.ts beats "the spawn module."
• Short over long. Two crisp sentences beat one paragraph almost every time. If a sentence has more than one comma, ask if it can be two sentences.
• Active over passive. "Port Daddy claims the port" not "the port is claimed by Port Daddy."
• Show the joinery. When two ideas connect — sessions and salvage, semantic identity and DNS, fleet YAML and the Arbiter — say so. The intelligence shows in the seams.

The First Rule

Show, don't explain.

The user said it: "the site explains what it's doing too much. It should just do it."

If a page says "this section helps you understand X" — delete the meta sentence and let the section do the work. If a hero says "Port Daddy is a local coordination service for AI agents" — show the actual command and its actual effect, and let the reader infer the category.

Seven rules

1. Lead with the reader's situation, not the product. A landing shouldn't open with "Port Daddy is..." — open with the problem the reader showed up with.
2. One claim per sentence. One job per paragraph. Stacking benefits ("fast, simple, and powerful") dilutes each one.
3. Use the actual command name in the actual font. pd begin, not "the begin command." Inline code is a credibility marker; it tells the reader this is real.
4. Cite the doc, don't paraphrase it. "See the salvage reference for the full flag list" is better than re-explaining salvage at half-depth.
5. Numbers and names are free credibility. "317 dead agents in the queue" beats "many dead agents." lib/fleet-engine.ts beats "the fleet engine."
6. Cut every sentence that starts with 'imagine,' 'simply,' 'just,' or 'we believe.' They signal that you're about to apologize for the product or wave at it instead of showing it.
7. Read it aloud. If you stumble, the reader will too.

Banned phrases

These words and phrases should not appear in user-facing copy without a specific defensible reason:

• "Powerful" / "robust" / "seamless" / "delightful" / "magical"
• "Imagine if..." / "Simply..." / "Just..."
• "We believe..." / "Our mission..." / "We think..."
• "In this section..." / "This page will explain..." / "Let's dive in..."
• "Loved by developers" / "Trusted by teams" (unless you can name them)
• "Transform your workflow" / "Supercharge your..." / "Unlock..."
• "Built different" / "Reimagined" / "Next-generation"
• "It's that simple" — it usually isn't, and saying so is condescending.
• Exclamation points outside of code blocks. The design carries emphasis; punctuation doesn't have to.

The seven rewriting moves

When editing existing copy, these are the moves that produce the biggest voice gains for the smallest effort.

1. Cut the meta sentence. "This page covers concepts" → just show concepts. "Below is the install guide" → just show the install command.
2. Replace category words with concrete examples. "Coordination primitives" → "ports, sessions, locks, channels."
3. Promote the verb. "Port Daddy provides session management" → "pd begin opens a session. pd done closes it."
4. Trade adjectives for numbers. "Comprehensive CLI" → "40 commands." "Battle-tested" → "shipping to production daily since v3.0."
5. Pull the deep link up. If the paragraph references a feature, inline the link. Don't make the reader hunt.
6. Convert questions into commands. "Wondering how to start?" → "Run pd setup." Questions invite passivity; commands invite action.
7. Test with the bounce question. Ask: "Has this paragraph done anything to keep the reader on the page or moved them toward an install?" If no, cut.

Before and after

These before/after pairs are calibrated against the actual website-v2 codebase. Use them as a forcing function when you're not sure if a sentence is doing work.

Hero copy

Before:

Port Daddy is a local-first coordination service that helps AI coding agents work together without conflict. Get started in minutes.

After:

Two agents try to edit the same file. The second one waits.

brew install curiositech/tap/port-daddy && pd setup

Section intro

Before:

In this section, we'll walk through the lifecycle of an agent session from start to finish, covering the begin and done commands and the notes you should leave along the way.

After:

An agent session has three steps: begin, note, done. Skip any one of them and Port Daddy can't recover the work later.

Feature description

Before:

Salvage is a powerful feature that allows you to recover work from agents that have terminated unexpectedly, ensuring no progress is lost.

After:

When an agent dies mid-task, its session sits in the salvage queue with the notes it left behind. Run pd salvage claim <id> to pick up where it stopped.

Sidebar label

Before:

Reference pages — Jump straight to the exact interface. The newer docs families improve reading order. The existing CLI, SDK, MCP, and API pages still matter when you need exact interfaces and older reference pages preserved.

After:

Reference — Jump straight to the exact interface. When you know what you want — a command, an SDK method, an MCP tool, or an HTTP endpoint.

(The "before" here is what was in the file before this PR; the "after" shipped in PR #23.)

Blog Post Writing

Blog posts are the highest-leverage surface on portdaddy.dev. A developer who finds one through Google or a friend's Slack message probably hasn't heard of Port Daddy — and that's fine, because the post is going to do the introducing. Write for them warmly. They're not a conversion funnel. They're a smart engineer who has already had a bad afternoon with a runaway agent, and they're looking for someone who gets it.

Voice for blog posts

Blog posts are where Erich's voice comes through most clearly. Not the shouty version — the generous, technically-excited, occasionally-digressive version that shows up when he's explaining something he genuinely loves. Here is what that sounds like, operationalized:

High-low collisions. A precise vocabulary word next to a very grounded one. "The canonical clock vector" and "the agent just quietly ate your file" belong in the same paragraph. Don't smooth the register into corporate evenness. The mismatch is not an error — it's the signal that a person wrote this.

Cathedral build, then punchline. Don't open with the product. Open with the situation in the world that made the product necessary. Six floors of context — the shape of the problem, a small story, maybe an analogy — then the product drops in near the bottom and lands clean. Section headers should work this way too: build the frame, then name the thing.

Em-dashes, parentheticals, asides. These are not noise to clean up; they are the clarity. They're how the reader knows a person wrote this rather than a content calendar. Use them. (Generic copywriting cuts the asides for "flow." The asides are the flow.)

Wild analogies. Every teaching page gets at least one. Pull from physics, linguistics, biology, history, kitchen chemistry — wherever the analogy lands cleaner than another paragraph of explanation. The reader doesn't have to recognize the source; the analogy's energy is what carries.

Lists with personality. Every bullet is a tiny short story, or it's better dissolved into prose. Bad: "Session recovery for crashed agents." Better: "When an agent dies mid-task — and it will — pd salvage is the record it left on its way down."

Be warm. The reader came here with a real problem. Meet them there, not at the product pitch. Assume they're clever. Assume they've already tried the obvious fix and it didn't work. The voice is collegial: you and I working through something together, not a product brief addressing a target persona.

Self-deprecation as ballast. The post can acknowledge that multi-agent coordination is genuinely hard, that the tooling is young, that the author has also lost a Saturday to this exact problem. Confidence and warmth in the same sentence. Don't perform invulnerability.

The zero-knowledge contract

Assume your reader:

• Has never run pd or seen the daemon before.
• Does not know what "sessions," "claims," "salvage," or "harbors" mean.
• Is running AI coding agents right now and has probably lost work at least once.
• Will follow Port Daddy jargon happily — but only after you've introduced the pain it names.

Rule: every Port Daddy concept must be earned. Introduce the problem, then introduce the primitive that solves it. Never lead with the primitive.

Before:

Port Daddy sessions give agents a durable identity so salvage can recover them.

After:

When an agent dies mid-task, the work it was doing evaporates. Port Daddy keeps a session open for every running agent — a named, timestamped record of what it was doing and what it left behind. When the agent crashes, pd salvage claim <id> picks up that record.

Required elements in every blog post

A Port Daddy blog post that ships without all five of these is not done:

1. At least two Mermaid diagrams. Flowcharts showing the problem state → Port Daddy intervention → resolved state. Sequence diagrams for multi-agent coordination flows. Architecture diagrams for system relationships. Diagrams are not decoration — they carry load that prose cannot. Use the mermaid language fence in the markdown:

   ```mermaid
   sequenceDiagram
     AgentA->>PD: pd claim src/auth.ts
     AgentB->>PD: pd claim src/auth.ts
     PD-->>AgentB: 409 Conflict — already claimed by AgentA
   ```
   

2. At least one code example per major concept. Real commands, real flags, real output. Not "run the claim command" — show pd claim src/auth.ts and what the terminal says back. The inline code fence is a credibility marker; use it for every command, flag, and file path mentioned.

3. At least two "Did You Know?" callouts for non-obvious facts, surprising edge cases, or counterintuitive behaviors. Format as a blockquote with a lead label:

   > **Did you know?** `pd salvage` doesn't just find crashed agents — it
   > finds *any* session whose TTL expired without a `pd done` call. That
   > includes agents you forgot about from last Tuesday.
   

4. At least three cross-links to the docs or other posts. Every concept that has a dedicated doc page gets a link on first mention. Every claim about Port Daddy behavior that the reader might want to verify gets a link. "See the salvage reference" beats re-explaining salvage at half-depth.

5. A concrete install or try-it CTA at or near the bottom. Not a banner — a sentence in the flow:

   If you're not running Port Daddy yet, brew install curiositech/tap/port-daddy takes under a minute. The quickstart has you coordinated in ten.

Post structure

The reader has 90 seconds before they decide whether this post is worth their time. Use that time well:

1. The hook (first two paragraphs): Lead with the concrete pain. Name a real scenario — agents colliding, work lost, a Saturday untangling a merge. No "in this post I'll cover" — open with the situation, not the syllabus.

2. The problem frame (3–6 paragraphs + diagram): Show the failure mode in detail. A Mermaid sequence or flowchart showing what goes wrong and why belongs here. The reader should see themselves in the failure.

3. The mechanism (body): Introduce Port Daddy's primitive. Define the term once, show the command, show the output. Interleave "Did You Know?" callouts for non-obvious behavior. Every jargon term gets a doc link.

4. Depth examples: At least one worked example with real commands and realistic output. If the post covers a multi-step workflow, a Mermaid sequence diagram goes here.

5. Why it's built this way: One short section explaining the design decision — why Port Daddy chose this primitive over a simpler one. This section is what makes senior engineers trust the product.

6. Try it / CTA: Close with a concrete next step. A command to run, a tutorial to follow, or a link to the relevant doc section.

Tone for blog posts: what to avoid

The site copy rules still apply. On top of them, these specific failures show up most in blog posts:

• Don't assert excitement — show the thing. "This is interesting because..." is a banned construction. Show the interesting thing and let the reader feel the click themselves.
• Don't use royal "we." "I" is fine when writing as the product builder. "We" means the author and the reader thinking together, not a company.
• Don't make headers neutral. "The Salvage System" is a label. "Salvage is a queue, not a graveyard" is an argument. Headers should take a position.
• Don't smooth the voice for legibility. The em-dashes, parentheticals, and asides are not decoration. If you find yourself cutting them for "clarity," you're making the post worse.
• Don't lecture. The reader is not a junior dev. They are probably smarter than most people who've used Port Daddy. Respect that.

Figures and callout taxonomy

Element	Use when	Markdown pattern
Mermaid flowchart	Problem state vs. resolved state	```mermaid\nflowchart TD\n...
Mermaid sequence	Multi-agent coordination	```mermaid\nsequenceDiagram\n...
Code block	Any command, config, or output	```bash\npd claim src/...\n
Did You Know?	Surprising behavior, non-obvious edge case	> **Did you know?** ...
Inline link	Every Port Daddy noun that has a doc page	[salvage](/docs/cli/salvage)
Numbered list	Sequential steps in a workflow	Standard markdown
Table	Comparing options, flags, or behaviors side-by-side	Standard markdown

Avoid: hero-image-only posts (every post needs at least one diagram inside the body, not just a cover image), posts with no code blocks, posts where the word "Port Daddy" only appears in the setup section and nowhere in the worked examples.

Where to apply this skill

Apply when editing or generating copy in:

• website-v2/src/components/landing/* — hero, CTAs, sections
• website-v2/src/components/site/* — sidebar labels, header copy
• website-v2/src/pages/**/*.tsx — page intros, section bodies
• website-v2/src/data/publicSite.ts, product.ts, siteMetadata.ts
• website-v2/src/docs-content/*.ts — docs content modules
• website-v2/src/data/docs-routes.ts — summary and intro strings
• Blog posts under website-v2/src/data/blog*.ts
• Whitepaper landing copy
• README.md user-facing sections
• Email, social, launch copy, screenshots' alt text

Do not apply to:

• ADR bodies (docs/adr/*.md) — keep internal voice
• Code comments and JSDoc
• Test descriptions
• Internal coordination notes (docs/recovery/*, .cartographer/*)
• CHANGELOG entries (those follow a separate convention)
• Skill files (these have their own voice)

How to know you're done

Run this checklist before committing copy changes:

1. Does the page open with the reader's problem or with a meta sentence? If meta, rewrite.
2. Does any paragraph reference a feature without linking to its doc? If yes, add the link.
3. Are there any banned phrases? Search for them; cut or rewrite.
4. Are there any sentences with more than one comma? Try splitting.
5. Are there any adjectives that don't pull weight? Replace with a number, a name, or nothing.
6. Read it aloud. Did you stumble? Did anything sound like a press release? Rewrite the stumble.
7. Bounce test: would a senior engineer reading this paragraph in 10 seconds either install Port Daddy or click through to a deeper page? If neither, the paragraph isn't earning its space.

If all seven pass, commit.

When the design and copy disagree

The Swiss-modern design treats whitespace as a primary element. If your copy is fighting for space, the design is signaling that the copy is saying too much. Trust the layout: cut.

Conversely, if a section feels visually empty, don't fill it with ornamental copy. Either let the whitespace stand or add a real piece of content (a code block, a deep link, a number). Ornamental copy is the single most common failure mode on portdaddy.dev today.

A final note on excitement

The voice is excited about new ideas — that's a real instruction, not a hedge. But excitement comes through specificity, not exclamation. The sentence "sessions, salvage, and the merge queue all hang off the same identity" is more exciting than "Port Daddy has an amazing identity system!" because the first sentence shows you something you didn't know and the second one demands you take a feeling on faith.

When you find a real connection — a primitive that turns out to compose with another in a non-obvious way — that's where the voice lights up. Show the connection. Let the reader feel the click.