2026-05-13 — petrova.codes content partition

Status: proposed Author: ops@devarno.cloud Decides for: distribution surface content strategy, domain ownership

Context

The Petrova fleet has three public surfaces:

petrova.blog — Astro + Starlight, launched with narrative methodology + playbook docs
petrova.host — operator console, control plane API
petrova.codes — unbuilt, reserved for artifact distribution

petrova.blog currently contains skill packs and prompts with human-readable prose. As petrova.codes is built out, there is a risk of content duplication: the same skills/prompts would be surfaced across both domains with no clear differentiation, leading to drift and maintenance burden.

PRODUCT.md defines the distribution consumer archetype: “a staff engineer or agent-fleet operator visiting once to pull a versioned skill pack, prompt, or CLI binary.” This is distinct from the blog audience — methodology readers, not task-completion seekers.

Decision

Establish a strict content partition between the two distribution surfaces:

petrova.blog (Substrate dialect) — narrative documentation:

How to use each skill (prose explanations, context)
What phases mean and how they work
Playbook methodology, concepts, meta-rules
Integration runbooks, recipes
Decision history with editorial framing
Target: someone learning the system

petrova.codes (Distribution dialect) — machine-consumable artifact registry:

Raw skill pack SKILL.md files (no wrapper prose)
Raw prompt files (no educational context)
Verb schemas (JSON, human-readable rendering)
Copy-to-clipboard install commands
Version pins and metadata
Machine-readable index (manifest.json, llms.txt)
Target: someone executing a task, pulling a cached skill, running a verb

Content flows one direction: blog links out to codes for raw downloads. codes does not link back to blog — it is self-contained and minimal.

Enforcement: pull-content.ts (the prebuild script for codes/) sources from:

skills/petrova-*/SKILL.md — raw skill content
core/prompts/*.md — raw prompts
spec/verbs/*.schema.json — schemas

No additional prose is authored for codes/. The layout is utilitarian (Distribution dialect). Audience is the CLI operator and agent fleets, not readers.

Alternatives considered

Unified surface, two views. One source tree, two rendered outputs. Rejected: increases infrastructure coupling, makes versioning/deployment strategy complex.
All content on .codes, link from .blog. Inverts the above. Rejected: blog has committed Starlight structure, would require massive refactor.
Deduplication by symlink. Share docs/site/ sections via symlinks in codes/. Rejected: unmaintainable, breaks Vercel builds, unclear ownership on edits.

Consequences

For code:

codes/scripts/pull-content.ts sources only skills/, core/prompts/, spec/verbs/ — never docs/site/.
site/scripts/pull-content.ts sources only docs/site/, never skills/ or spec/verbs/.
codes/ layout is Distribution dialect only — no Starlight, no navbar, task-optimized.

For docs:

docs/site/ remains the narrative space for blog.
skills/petrova-*/SKILL.md is authored once, consumed by both blog (as reference material) and codes/ (as raw download).
New prose about skills goes into docs/site/skills/, not into skill pack bodies.

For in-flight phases:

Phase launches for petrova-codes surface align with TASKSET 5 completion.

For invariants:

MR-3 (sibling files). skills/petrova-*/SKILL.md is a sibling to both domains; both read from it, no duplication of body.
MR-7 (decisions append-only). This decision records the partition; future conflicts resolved via new decision doc, never silent edits.

References

PRODUCT.md — distribution consumer definition
DESIGN.md — Distribution dialect spec
docs/decisions/2026-05-08-petrova-domain-pivot.md — domain acquisition and brand axis
codes/ scaffold design (TASKSET 0–4 plan)

Sign-off

Subagent: OpenCode planning session (synthesis analysis)
Human: awaiting confirmation