// 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).
Instruction manual for agents driving Port Daddy multi-agent coordination. Use when an agent will edit a repo, recover work, coordinate with other sessions, inspect FleetBar/Fleet Control Center truth, package skill/docs surfaces, or leave a durable handoff. NOT for generic coding that does not need Port Daddy state.
Contributor manual for agents working ON the Port Daddy codebase itself — the daemon, MCP server, FleetBar / Fleet Control Center, website, CLI surface, distribution mirrors, internal recovery ledger, and the named internal actors (Coxswain / Navigator / Cartographer / Lookout / Quartermaster + Shipwright). Use when editing the port-daddy repo. NOT for agents using Port Daddy on other projects (use port-daddy-agent-skill for that), and NOT distributed to public skill catalogs — this skill is private to the port-daddy repo.
Instruction manual for agents driving Port Daddy multi-agent coordination. Use when an agent will edit a repo, recover work, coordinate with other sessions, inspect FleetBar/Fleet Control Center truth, package skill/docs surfaces, or leave a durable handoff. NOT for generic coding that does not need Port Daddy state.
Architects Port Daddy's outbound-only event relay and the zero-trust crypto stack that governs it — PKI choice (ACME vs OIDC vs Web-of-Trust), per-publisher Merkle event chains, harbor cards on the wire, Phase 3 capability attenuation, E2E payload encryption, ProVerif extension, and the V4 remote-harbor redefinition. Use when designing the relay, writing the PKI/relay/V4 ADRs, deciding PKI strategy with proponent/pragmatic/antagonist deliberation, scaffolding ACME or OIDC, building Merkle chain primitives, or extending the symbolic protocol model. NOT for implementing the local daemon, generic harbor-card refactors, Float Plan economic settlement (deferred), or generic zero-trust theory (use agentic-zero-trust-security).
Defensive security and mechanization fleet for the Port Daddy whitepapers (Bonded Commons, Anchor Protocol). Use when responding to red-team findings in a versioned round, when closing a cited-but-unmodeled proof, or when proposing the next paper version bump. NOT for ad-hoc code review — see code-reviewer skill.
Adversarial security review fleet for the Port Daddy whitepapers (Bonded Commons, Anchor Protocol). Use when a paper version is being prepared, when a coordination/cryptographic claim is being added, or when paired with the whitehat-defense skill in a versioned red-vs-white iteration round. NOT for production threat response — see SECURITY.md for incident handling.
| 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"]}} |
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.
Senior engineers, indie devs, and tech leads who:
git reset --hard collision, or have been told it
could happen.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.
brew install curiositech/tap/port-daddy, ask why it exists.Technically competent. Persuasive without being supercilious. Excited about ideas, especially the ways primitives compose. Direct.
lib/spawner.ts beats "the spawn module."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.
pd begin, not
"the begin command." Inline code is a credibility marker; it tells the
reader this is real.lib/fleet-engine.ts beats "the fleet
engine."These words and phrases should not appear in user-facing copy without a specific defensible reason:
When editing existing copy, these are the moves that produce the biggest voice gains for the smallest effort.
pd begin opens a session. pd done closes it."pd setup." Questions invite passivity; commands invite action.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.
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
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.
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.
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 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.
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.
Assume your reader:
pd or seen the daemon before.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.
A Port Daddy blog post that ships without all five of these is not done:
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
```
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.
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.
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.
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-daddytakes under a minute. The quickstart has you coordinated in ten.
The reader has 90 seconds before they decide whether this post is worth their time. Use that time well:
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.
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.
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.
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.
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.
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.
The site copy rules still apply. On top of them, these specific failures show up most in blog posts:
| 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.
Apply when editing or generating copy in:
website-v2/src/components/landing/* — hero, CTAs, sectionswebsite-v2/src/components/site/* — sidebar labels, header copywebsite-v2/src/pages/**/*.tsx — page intros, section bodieswebsite-v2/src/data/publicSite.ts, product.ts, siteMetadata.tswebsite-v2/src/docs-content/*.ts — docs content moduleswebsite-v2/src/data/docs-routes.ts — summary and intro stringswebsite-v2/src/data/blog*.tsREADME.md user-facing sectionsDo not apply to:
docs/adr/*.md) — keep internal voicedocs/recovery/*, .cartographer/*)Run this checklist before committing copy changes:
If all seven pass, commit.
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.
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.