@profile-as-code/cli 0.3.6 → 0.4.0

package/skills/github-repo-meta/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: github-repo-meta
+description: >
+  Superficie de presencia `github-repo-meta` (D23, #262): la metadata del
+  artefacto de código — descripción del repo, topics, social preview, release
+  notes y la página npm derivada. Convierte un release en presencia visible
+  sobre el repo, sin inventar hechos: la descripción y las notas salen del
+  release plan (`pasco release plan`) y del SSOT, nunca de la memoria del agente.
+model: mecánico (la copy es corta y acotada; el juicio de posicionamiento vive en
+  la skill de la README del perfil)
+applies_to: github-repo-meta
+projection: agent-agnostic (AionUi, OpenHands, Claude Code, Cursor, pi…)
+version: 0.1.0
+status: draft (D23, #262)
+sources: "platforms/registry.yaml (kind: repo-meta) · docs/SPEC.md §22"
+---
+
+# GitHub repo metadata — skill de superficie repo-meta (D23)
+
+## Misión
+
+Que un release exista como **presencia**: el repo se encuentra, se entiende y se
+comparte. El motor no renderiza esta superficie (no hay renderer: es HTML/API de
+GitHub); lo que el motor SÍ da es el **plan**: `pasco release plan <id>` nombra la
+superficie, su estado derivado del ledger y la **espina factual** del release. Esta
+skill es la capa de juicio que convierte esa espina en metadata publicable.
+
+## Regla de oro
+
+> La metadata del repo describe el **artefacto**, no a la persona. El perfil
+> (github-readme) es la voz; `github-repo-meta` es la ficha: qué es esto, para
+> quién, y qué cambió.
+
+- La descripción NO repite el positioning personal: dice qué hace el repo.
+- Los facts (versión, fecha, link) salen del release row y del SSOT; si un dato
+  no está, no se escribe.
+- Un release = una pasada. No optimices metadata sin release: sin evento, la
+  superficie queda `never` en el plan (y eso es correcto, D23).
+
+## Flujo
+
+1. **Plan**: `pasco release plan <release-id> --json` → la fila
+   `github-repo-meta` (estado) + `baseText[kind=repo-meta]` (la espina factual).
+   Sin `releases[]` en el workspace, el comando falla con la razón: agregá el
+   release primero (schema v1.15).
+2. **Composición** (juicio, esta skill):
+   - `description` ≤350 chars, la promesa del artefacto + una señal de para quién.
+   - `topics` ≤20, minúsculas, guiones; genéricos primero, específicos después.
+   - release notes: `baseText` como primer párrafo + `changedUnits` como bullets
+     verificables; nada de métricas sin fuente.
+   - social preview 1280×640 (el preview se sube a mano: no hay API).
+3. **Deploy** (API de GitHub, D9):
+   ```sh
+   gh repo edit --description "<description>" --add-topic <topic> …
+   gh release edit <tag> --notes-file <notas.md>
+   ```
+4. **Verificación** (playbook.md, sección "Verificación post-deploy"): la
+   lectura de vuelta con `gh repo view --json description,repositoryTopics` y la
+   inspección visual del social preview.
+5. **Cierre del loop**: en v1 el ledger solo direcciona las superficies del enum
+   de perfiles; `github-repo-meta` no tiene record y el plan la lee `never`. Es
+   un límite declarado (D23): el plan nombra lo que falta tocar; extender la
+   clave de superficie del ledger es un cambio de contrato aparte.
+
+## Límites y trampas
+
+- **Descripción duplicada**: si el repo y la página npm dicen lo mismo, es señal
+  de que el release no cambió nada relevante; no reescribas por inercia.
+- **Topics como hashtags**: no son keywords de marketing; son el índice por el
+  que un desconocido encuentra el artefacto.
+- **Notas = changelog completo**: el release note es la parte que le importa a
+  quien evalúa adoptar; el detalle vive en CHANGELOG.
+- **Social preview desactualizado**: es la única pieza sin API; verificala a
+  mano o no cuenta como publicada.
+
+## Checks
+
+`checks.yaml` declara los criterios con la misma forma que el resto de las skills
+(`rule` del catálogo, `platform: github-repo-meta`). En v1 `pasco check` no
+ejecuta una superficie fuera del enum de perfiles: el catálogo queda declarado
+para cuando la superficie tenga renderer, y hoy la verificación es la del
+playbook.

package/skills/github-repo-meta/checks.yaml

@@ -0,0 +1,50 @@
+# checks.yaml — criterios de la superficie `github-repo-meta` (D23, #262)
+# Misma forma que el catálogo de `pasco check` (rule + value + note). v1: el
+# engine no renderiza esta superficie y `pasco check` no la ejecuta (no está en
+# el enum de perfiles); el catálogo queda declarado y la verificación es la del
+# playbook. Los caps citados son límites oficiales de GitHub.
+
+- id: repo-description-max
+  platform: github-repo-meta
+  rule: max-chars
+  value: 350
+  surface: bio
+  note: "La descripción del repositorio se trunca a 350 caracteres en la UI. [OFICIAL] docs.github.com (customizing-your-repository), leído 2026-10-29."
+
+- id: repo-description-min
+  platform: github-repo-meta
+  rule: min-chars
+  value: 40
+  surface: bio
+  note: "Una descripción de menos de 40 chars no dice qué hace el artefacto; el piso es juicio de esta skill, no un límite de GitHub."
+
+- id: repo-topic-max-chars
+  platform: github-repo-meta
+  rule: max-chars
+  value: 50
+  surface: headline
+  note: "Cada topic tiene un máximo de 50 caracteres (regla de largo, no de conteo). GitHub permite además hasta 20 topics por repositorio: ese tope es de CANTIDAD y el catálogo no tiene una regla de conteo — lo verifica el playbook (paso 5), no esta fila. [OFICIAL] docs.github.com (customizing-your-repository), leído 2026-10-29."
+
+- id: repo-facts-ssot
+  platform: github-repo-meta
+  rule: fact-present
+  value: true
+  note: "La versión, la fecha y el link de la metadata salen del release row (`pasco release plan`) y del SSOT; un dato que la superficie agrega y el SSOT no tiene es un FAIL de revisión (no lo ejecuta pasco check en v1)."
+
+- id: repo-links-identity
+  platform: github-repo-meta
+  rule: link-in-identity
+  value: true
+  note: "Toda URL escrita en la descripción o las notas vive en `identity.links` (regla drift §15.4)."
+
+- id: repo-geo-consistent
+  platform: github-repo-meta
+  rule: geo-consistent
+  value: true
+  note: "Los hechos de la metadata coinciden con el resto de superficies (README, npm): misma versión, mismo nombre, mismo link canónico."
+
+- id: repo-lang-en
+  platform: github-repo-meta
+  rule: lang-present
+  value: en
+  note: "La metadata del artefacto va en EN (D8/§11) aunque las notas del release puedan traducirse; el repo es la superficie internacional."

package/skills/github-repo-meta/playbook.md

@@ -0,0 +1,45 @@
+# GitHub repo metadata — deploy playbook
+
+Deploy = **API de GitHub** (D9): la metadata se escribe con `gh` (REST/GraphQL),
+no se pega a mano en la UI. El social preview es la única pieza sin API — se
+sube a mano y se verifica visualmente.
+
+Superficie: `github-repo-meta` (`kind: repo-meta`, D23/#262). Estado esperado en
+el plan: `never` mientras el ledger no pueda direccionar la superficie (límite
+declarado v1).
+
+## Flujo
+
+1. **Plan**: `pasco release plan <release-id> --json` → `surfaces[]` trae la fila
+   `github-repo-meta` y `baseText` la espina factual del release.
+2. **Componer** (ver SKILL.md): `description` ≤350 chars · `topics` ≤20 ·
+   release notes desde `changedUnits`.
+3. **Deploy**:
+   ```sh
+   gh repo edit --description "<description>"
+   gh repo edit --add-topic <topic>        # repetir por topic nuevo
+   gh release edit <tag> --notes-file <notas.md>
+   ```
+4. **Social preview**: subir 1280×640 (Settings → Social preview). Sin API.
+5. **Verificar** (ver abajo) y reportar el resultado en el PR/issue del release.
+
+## Verificación post-deploy
+
+- [ ] `gh repo view --json description --jq .description` devuelve la descripción
+      publicada, y no pasa de 350 chars.
+- [ ] `gh repo view --json repositoryTopics --jq '.repositoryTopics[].name'`
+      devuelve exactamente los topics declarados (≤20), sin duplicados.
+- [ ] `gh release view <tag> --json body --jq .body` devuelve las notas y el
+      primer párrafo cita la versión + fecha del release row.
+- [ ] El social preview se ve en la página del repo (1280×640, sin texto
+      recortado) — inspección visual, es la excepción sin API.
+- [ ] La descripción describe el artefacto, no repite el positioning personal de
+      `github-readme`.
+- [ ] Ningún número de las notas carece de fuente (regla de evidencia).
+
+## Rollback
+
+`gh repo edit` es aditivo y versionable en git no: guardá la descripción y los
+topics anteriores antes de escribir (`gh repo view --json description,repositoryTopics`).
+Revertir = repetir el paso 3 con los valores previos; las release notes se
+revierte con `gh release edit <tag> --notes-file <previas.md>`.

package/skills/hashnode/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: hashnode-post
+description: >
+  Long-form post skill for Hashnode. Says what a Hashnode article is for and how
+  the agent writes it; the machine contract is
+  skills/hashnode/longform.yaml (required/optional fields, editorial word band,
+  export: api). The judgment layer — shape, voice, GEO, i18n — lives in post.md.
+  The agent writes N variants, the operator picks one, and the choice is recorded
+  with `pasco post choose`.
+model: juicio (frontier) — the technical claim and its example are judgment; the
+  mechanical parts (markdown, front matter) are not
+applies_to: hashnode
+projection: agent-agnostic (any harness that reads Markdown and can run the CLI)
+version: 0.1.0
+status: draft (#361)
+sources: skills/hashnode/longform.yaml
+---
+
+# Hashnode long-form — skill
+
+## Mission
+
+Turn one canonical seed into a Hashnode article a developer can build from: the
+problem, a runnable example, the reasoning, the caveats. The skill is the
+judgment layer (D5); the contract plus `pasco post check` are the deterministic
+part.
+
+## When it runs
+
+`pasco post task <seed> --format longform --channel hashnode` emits a task bundle
+that points at the contract (`longform.yaml`) and the judgment file (`post.md`);
+it does **not** carry this `SKILL.md`. This file is the channel's strategy
+reference for whoever opens it directly: read the contract for the fields and the
+band, then `post.md` for how to write.
+
+Do **not** run `pasco refine hashnode` for this channel. Refine is the profile
+command: with a `SKILL.md` now present it resolves this file instead of answering
+"no skill for hashnode yet", and emits a **profile** task ("write N variants of
+the hashnode profile") that saves to `profiles/hashnode/variants/<id>.md` — not a
+post workflow. Telling a profile skill from a post skill is an engine decision,
+not something this skill can fix.
+
+## Flow
+
+1. Read `longform.yaml` + `post.md`; do not re-derive the limits.
+2. Write N variants as YAML front matter + markdown body, at
+   `posts/<seed>/hashnode/hashnode-<n>.md`.
+3. The operator picks one; record it with `pasco post choose`.
+4. `pasco post check` — fix the findings.
+5. `pasco post export <seed> --target postiz` for the API draft payload.
+6. Publish manually, then verify the live page (title, tags, canonical).
+
+## Contract pointers (single source each)
+
+| Question | Home |
+|---|---|
+| required / optional fields | `longform.yaml` `fields` |
+| editorial word band | `longform.yaml` `limits.words` (not a platform cap) |
+| api vs paste | `longform.yaml` `export` |
+| link policy | `longform.yaml` `links.policy` (`identity-ssot-only`) |
+| dated platform sources | `longform.yaml` `sources[]` |
+| how to write the piece | `post.md` |
+
+## GEO and i18n
+
+Public, indexed article page; tags are the arrival paths; the citation unit is
+the snippet plus the claim it proves. Write `en` by default, and treat a Spanish
+article as a separate seed for that audience — never a duplicate of the English
+one under a shared canonical. The crawler stance is the repo's global `ai.policy`
+(`platforms/registry.yaml`, v1, 2026-10-27).
+
+## Verification
+
+- `pasco post check` exit 0 (no `missing-field`, `word-count` or
+  `url-not-in-ssot` errors).
+- Every code block runs as printed; every version is stated.
+- Facts byte-identical to the SSOT; every URL from the identity SSOT.
+- Report any contract gap as a finding — the engine is not extended from a
+  skill (#361).

package/skills/hashnode/longform.yaml

@@ -0,0 +1,33 @@
+# hashnode long-form rules — machine-readable (#266)
+#
+# Read by `pasco post task|check|export` when the seed is `format: longform`.
+# The word range is an EDITORIAL default (the operator's house style), NOT a
+# platform limit: cite a platform source before encoding a hard cap here.
+
+platform: hashnode
+format: longform
+export: api
+settings:
+  __type: hashnode
+fields:
+  required:
+    - title
+    - dek
+  optional:
+    - tags
+    - canonical
+    - publication
+limits:
+  words:
+    min: 600
+    max: 3000
+links:
+  policy: identity-ssot-only
+structure:
+  - title
+  - dek
+  - sections
+sources:
+  - url: https://apidocs.hashnode.com/
+    date: 2026-10-29
+    note: "Hashnode's GraphQL API publishes posts with a title, tags and markdown content."

package/skills/hashnode/post.md

@@ -0,0 +1,90 @@
+# Hashnode long-form post — skill (MVP)
+
+> Long-form post skill. The contract is `longform.yaml`: required/optional
+> fields, the editorial word band and `export` live there and are **not**
+> restated here — this file is the judgment layer the agent reads before
+> writing. The contract's `sources[]` carries the dated URL for every platform
+> claim; re-verify before making a hard one, and cite a source (date + tier)
+> before calling anything a limit.
+
+## What a Hashnode piece is for
+
+A technical article published on a developer blogging network — the network feed
+plus, optionally, a publication. It is the "write it once, let it be found by
+developers" surface: an idea, a working example and the reasoning between them.
+It is not a copy of the newsletter issue with a different header.
+
+## Shape
+
+1. **Title** — what the reader can build or decide after reading. No curiosity
+   gap that the body does not close.
+2. **Dek** — one line of scope: the problem, the approach, the result. The
+   contract requires it as a field and the engine delivers it as front matter,
+   never as the body's first lines. No platform mapping is declared; confirm on
+   the first publish how Hashnode renders it [?].
+3. **Sections** — an opening that states the problem, then one H2 per step of
+   the solution, then the caveats. Code is the evidence: show it, state the
+   version, and keep it runnable.
+
+## Rules
+
+- **Front matter is the field contract.** `longform.yaml` declares the fields this
+  channel consumes, required and optional alike; the engine exports only those,
+  and an undeclared field is dropped (`pasco post check` warns `unknown-field`) —
+  never smuggle one into the body instead.
+- **Length:** the band in `limits.words` is the operator's editorial default (the
+  contract says so in its header), not a platform cap. It is a guardrail for a
+  piece read in one sitting.
+- **Links:** `links.policy` is `identity-ssot-only`. `canonical` points at the
+  canonical home from the SSOT when the piece is syndicated; a network URL is
+  never the canonical for another channel's copy unless the SSOT says so.
+- **Facts:** `{{fact:<pointer>}}` for every number, date, version and URL.
+- **Voice:** first person technical, second person for the reader ("you"); no
+  hype, no "revolutionary".
+
+## Export: `api`
+
+The contract declares `export: api`: the body is markdown published through
+Hashnode's GraphQL API, with the title, tags and markdown content in the mutation
+[OFICIAL — the contract's source, `sources[]` in `longform.yaml`, dated
+2026-10-29]. Consequences for the writing:
+
+- Markdown only; no raw HTML or editor-only embeds.
+- `publication` is a payload field (which blog the post belongs to) — it is not
+  a body line and it is not the author profile.
+- The export produces a Postiz draft payload; publishing stays manual (no
+  scheduler, no OAuth — `docs/post-mvp.md`).
+
+## GEO (how this channel is read and cited)
+
+Hashnode article pages are public and indexed, and the tags are the paths readers
+arrive from. The quotable unit is the code block plus the sentence that says what
+it proves — so keep the claim adjacent to the snippet. The crawler stance is the
+repo's global `ai.policy` (`platforms/registry.yaml`, v1, 2026-10-27); no
+per-channel rule is invented here. Consistency check: version numbers, dates and
+claims match the SSOT byte for byte, same as the profile.
+
+## i18n
+
+The network's audience and tag vocabulary are English-first: write `en` by
+default. A Spanish article is its own seed for that audience, not a translation
+of the English one, and it must not share a canonical with it.
+
+## Anti-patterns
+
+- A tutorial whose code cannot run as printed.
+- A "getting started" post that is only a link to someone else's docs.
+- Tag stuffing to reach feeds the piece does not belong to.
+- Cross-posting without `canonical`.
+- Numbers with no method, date or source.
+
+## Output contract
+
+Save each variant as YAML front matter + a markdown body at
+`posts/<seed>/hashnode/hashnode-<n>.md`, then record the choice and check it:
+
+```
+pasco post choose <seed> --channel hashnode --variant hashnode-1
+pasco post check <seed>     # missing-field · word-count · url-not-in-ssot · unknown-field
+pasco post export <seed> --target postiz
+```

package/skills/hotmart/checks.yaml

@@ -1,5 +1,8 @@
 # checks.yaml — criterios machine-readable para `pasco check hotmart`
-# (unión con content/checks.yaml del workspace; misma rule catalog que el schema).
+# Misma rule catalog que el schema; la unión con content/checks.yaml decide qué
+# premisas corren (fact-present) y los caps de caracteres salen del catálogo del
+# workspace cuando declara checks — entero, sin merge por fila — o de los defaults
+# del paquete; nunca de estas filas (SPEC §7, pasco check).
 #
 # Fuente de los valores: research/SOTA-2026.md (todas las fuentes fechadas
 # 2026-10-05). Hotmart NO documenta límite para el cuerpo de perfil [?] — no
@@ -16,7 +19,7 @@
   platform: hotmart
   rule: fact-present
   value: true
-  note: "Hechos del cuerpo byte-idénticos al SSOT (D4); el cuerpo es el cierre de confianza del storefront (SOTA-2026 §1)."
+  note: "El cuerpo que escribió `pasco build` se compara contra el render actual del SSOT en los dos sentidos — URL, fecha o número agregado u omitido, y texto sin token que lo explique (WARN, D12; `pasco audit` lo gradúa); el cuerpo es el cierre de confianza del storefront (SOTA-2026 §1). `link-in-identity` es una premisa aparte."
 
 - id: h-links-identity
   platform: hotmart

package/skills/kofi/checks.yaml

@@ -1,5 +1,8 @@
 # checks.yaml — criterios machine-readable para `pasco check kofi`
-# (unión con content/checks.yaml del workspace; misma rule catalog que el schema).
+# Misma rule catalog que el schema; la unión con content/checks.yaml decide qué
+# premisas corren (fact-present) y los caps de caracteres salen del catálogo del
+# workspace cuando declara checks — entero, sin merge por fila — o de los defaults
+# del paquete; nunca de estas filas (SPEC §7, pasco check).
 #
 # Fuente de los valores: research/SOTA-2026.md (todas las fuentes fechadas
 # 2026-10-05). Ko-fi NO documenta límite para el About [?] — el max-chars es
@@ -15,7 +18,7 @@
   platform: kofi
   rule: fact-present
   value: true
-  note: "Hechos del About byte-idénticos al SSOT (D4); el About es el cuerpo del perfil (SOTA-2026 §5)."
+  note: "El About que escribió `pasco build` se compara contra el render actual del SSOT en los dos sentidos — URL, fecha o número agregado u omitido, y texto sin token que lo explique (WARN, D12; `pasco audit` lo gradúa); el About es el cuerpo del perfil (SOTA-2026 §5). `link-in-identity` es una premisa aparte."
 
 - id: k-links-identity
   platform: kofi
@@ -39,4 +42,4 @@
   platform: kofi
   rule: lang-present
   value: en
-  note: "EN requerido (D8/§11); compile no hace fallback por fila de bios — artefacto vacío = gap visible."
+  note: "EN requerido (D8/§11); compile no hace fallback por fila de bios — artefacto vacío = gap visible."

package/skills/listmonk/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: listmonk-post
+description: >
+  Long-form post skill for listmonk — a self-hosted email campaign to named
+  lists, not a feed. Says what the issue is for and how the agent writes it; the
+  machine contract is skills/listmonk/longform.yaml (required/optional fields,
+  the tightest editorial word band of the long-form channels, export: api). The
+  judgment layer — subject line, shape, GEO, i18n — lives in post.md. The agent
+  writes N variants, the operator picks one and the list, and the choice is
+  recorded with `pasco post choose`.
+model: juicio (frontier) — the subject line and the single action are judgment;
+  the mechanical parts (markdown, front matter) are not
+applies_to: listmonk
+projection: agent-agnostic (any harness that reads Markdown and can run the CLI)
+version: 0.1.0
+status: draft (#361)
+sources: skills/listmonk/longform.yaml
+---
+
+# listmonk long-form — skill
+
+## Mission
+
+Turn one canonical seed into one email issue that a subscriber reads to the end
+and acts on once. The reader opted in, so the piece owes them a letter: a
+subject that states the value, a body that delivers it, one action at the close.
+The skill is the judgment layer (D5); the contract plus `pasco post check` are
+the deterministic part.
+
+## When it runs
+
+`pasco post task <seed> --format longform --channel listmonk` emits a task bundle
+that points at the contract (`longform.yaml`) and the judgment file (`post.md`);
+it does **not** carry this `SKILL.md`. This file is the channel's strategy
+reference for whoever opens it directly: read the contract for the fields and the
+band, then `post.md` for how to write.
+
+Do **not** run `pasco refine listmonk` for this channel. Refine is the profile
+command: with a `SKILL.md` now present it resolves this file instead of answering
+"no skill for listmonk yet", and emits a **profile** task ("write N variants of
+the listmonk profile") that saves to `profiles/listmonk/variants/<id>.md` — not a
+post workflow. Telling a profile skill from a post skill is an engine decision,
+not something this skill can fix.
+
+## Flow
+
+1. Read `longform.yaml` + `post.md`; the band is narrower here, and the contract
+   — not this file — is where its numbers live.
+2. Write N variants as YAML front matter + markdown body, at
+   `posts/<seed>/listmonk/listmonk-<n>.md`.
+3. The operator picks one and the target `list`; record the choice with
+   `pasco post choose`.
+4. `pasco post check` — fix the findings.
+5. `pasco post export <seed> --target postiz` for the campaign draft payload.
+6. Send manually; the operator owns consent, unsubscribes and deliverability.
+
+## Contract pointers (single source each)
+
+| Question | Home |
+|---|---|
+| required / optional fields | `longform.yaml` `fields` (`list` selects the audience) |
+| editorial word band | `longform.yaml` `limits.words` (not a platform cap) |
+| api vs paste | `longform.yaml` `export` |
+| link policy | `longform.yaml` `links.policy` (`identity-ssot-only`) |
+| dated platform sources | `longform.yaml` `sources[]` |
+| how to write the issue | `post.md` |
+
+## GEO and i18n
+
+Email is not crawlable: citation depends on the same text existing on a public
+surface, with facts byte-identical to this issue. One list per language, one
+language per issue; `en` by default. The crawler stance is the repo's global
+`ai.policy` (`platforms/registry.yaml`, v1, 2026-10-27).
+
+## Verification
+
+- `pasco post check` exit 0 (no `missing-field`, `word-count` or
+  `url-not-in-ssot` errors).
+- Subject (title), dek and preview are three different sentences doing three
+  different jobs.
+- Exactly one call to action; every URL from the identity SSOT.
+- Report any contract gap as a finding — the engine is not extended from a
+  skill (#361).

package/skills/listmonk/longform.yaml

@@ -0,0 +1,33 @@
+# listmonk long-form rules — machine-readable (#266)
+#
+# Read by `pasco post task|check|export` when the seed is `format: longform`.
+# The word range is an EDITORIAL default (the operator's house style), NOT a
+# platform limit: cite a platform source before encoding a hard cap here.
+
+platform: listmonk
+format: longform
+export: api
+settings:
+  __type: listmonk
+fields:
+  required:
+    - title
+    - dek
+  optional:
+    - preview
+    - publication
+    - list
+limits:
+  words:
+    min: 400
+    max: 1500
+links:
+  policy: identity-ssot-only
+structure:
+  - title
+  - dek
+  - sections
+sources:
+  - url: https://listmonk.app/docs/apis/apis/
+    date: 2026-10-29
+    note: "listmonk's API creates a campaign with a body and one or more list ids; the audience is the list, not a channel."

package/skills/listmonk/post.md

@@ -0,0 +1,93 @@
+# listmonk long-form post — skill (MVP)
+
+> Long-form post skill. The contract is `longform.yaml`: required/optional
+> fields, the editorial word band and `export` live there and are **not**
+> restated here — this file is the judgment layer the agent reads before
+> writing. The contract's `sources[]` carries the dated URL for every platform
+> claim; re-verify before making a hard one, and cite a source (date + tier)
+> before calling anything a limit.
+
+## What a listmonk piece is for
+
+One email campaign to one or more lists the reader already subscribed to. The
+audience is the list, not a feed: there is no discovery, no search surface and no
+second chance — the subject line decides whether the issue is read at all. The
+piece is a letter to a named group, not a post that hopes to be found.
+
+## Shape
+
+1. **Title** — the subject line. It is what the reader sees first and the only
+   line that competes with an inbox; state the value of opening, not the topic.
+2. **Dek** — the line that sets up the issue: why this, why now. Where the
+   channel renders a preview line, the optional `preview` field carries it — the
+   contract declares both, and they must not say the same thing.
+3. **Sections** — an email is read top to bottom in one sitting: lead with the
+   point, then the evidence, then one action. Short paragraphs, no nested
+   headings, no "read more" link as the only payload.
+
+## Rules
+
+- **Front matter is the field contract.** `longform.yaml` declares the fields this
+  channel consumes, required and optional alike; the engine exports only those,
+  and an undeclared field is dropped (`pasco post check` warns `unknown-field`).
+  The field that selects the audience is a targeting decision, not prose: choose
+  it deliberately, and never send one issue to a list it was not written for.
+- **Length:** the band in `limits.words` is the operator's editorial default (the
+  contract says so) — and it is the tightest of the long-form channels, because
+  the channel is read in one sitting, not skimmed. Do not pad to reach it and do
+  not assume the ceiling is the goal.
+- **Links:** `links.policy` is `identity-ssot-only`. An email has no canonical
+  field in the contract, so the SSOT is the only URL source and the archive copy
+  (if any) is the only place a URL can be cited from.
+- **Facts:** `{{fact:<pointer>}}` for every number, date and URL.
+- **Voice:** direct, personal, no marketing cadence. Match `brandVoice`; a
+  newsletter that sounds like a press release is an unsubscribe.
+
+## Export: `api`
+
+The contract declares `export: api`: listmonk's API creates a campaign with a
+body and one or more list ids [OFICIAL — the contract's source, `sources[]` in
+`longform.yaml`, dated 2026-10-29]. Consequences:
+
+- The body is markdown/HTML the campaign carries; keep it paste-safe and
+  email-safe (no scripts, no layout that only a browser renders).
+- The audience is a `list` id, not a channel: the send is a targeting decision
+  the operator makes, and this skill never picks it for them.
+- The export produces a draft payload; sending stays manual.
+- Consent, unsubscribe mechanics and deliverability are the operator's
+  responsibility and out of scope here.
+
+## GEO (how this channel is read and cited)
+
+Email is not a crawlable surface: an issue that exists only in an inbox is
+invisible to search and to citation. Citability therefore depends on the same
+text also existing where it can be linked and quoted — if it matters, mirror it
+to a public surface whose URL the SSOT already carries, and keep the two copies
+byte-identical in their facts. The crawler stance is the repo's global
+`ai.policy` (`platforms/registry.yaml`, v1, 2026-10-27); no per-channel rule is
+invented here.
+
+## i18n
+
+The list is the segmentation: one list per language, and one language per issue.
+Write `en` by default; a Spanish issue goes to the Spanish list, not to every
+list. Do not machine-translate an issue and send both to the same audience.
+
+## Anti-patterns
+
+- A subject line that is the article title ("On X") with no reason to open.
+- A dek and a preview that repeat each other.
+- An issue with five calls to action.
+- Marketing cadence in a letter ("Don't miss out!").
+- Sending a piece written for one audience to a list it does not fit.
+
+## Output contract
+
+Save each variant as YAML front matter + a markdown body at
+`posts/<seed>/listmonk/listmonk-<n>.md`, then record the choice and check it:
+
+```
+pasco post choose <seed> --channel listmonk --variant listmonk-1
+pasco post check <seed>     # missing-field · word-count · url-not-in-ssot · unknown-field
+pasco post export <seed> --target postiz
+```