v1.1.0 - Security and Correctness Stabilization

See PR #10 for details.

What's changed

Payload Markdown Docs 1.1.0

Release 1.1.0 includes changes to sync security, sync apply integrity, read visibility, the native pmdocs CLI, plugin configuration, routing and links, release tooling, packaging, docs contract, and tests.

Sync Security

Sync security defaults to admin-only access, scopes credentials to docs sets, prevents nonce replay, narrows OIDC trust, and restricts asset serving.

• Plugin collections default to admin-only; config.admin.user or access.admin grants admin CRUD, with per-collection overrides replacing operations.
• Sync credentials and resolved keys carry docsSetIds; isDocsSetInScope authorizes sync only when scope is empty or includes the target docs set.
• Nonce consumption inserts first and rejects replays when the unique (keyId, nonce) index is missing; the 1.1 migration removes expired nonces and keeps the oldest duplicate row.
• GitHub OIDC pull_request tokens are checked against their base branch; per-docs-set trust limits allowed repositories, tag refs, workflow refs, and branch.
• Asset content types are restricted to allowed docs asset types; responses add nosniff and CSP headers; draft assets are deferred on non-publish syncs.

Sync Apply Integrity

Sync apply is transactional, releases routes on archive, archives dropped assets, protects manual edits, and updates docs-set sync bookkeeping.

• Sync apply runs in a database transaction when beginTransaction is available; success commits, error rolls back, and failed apply marks the sync run failed.
• Archived docs release their unique route during delete or replacement so renames, slug swaps, and moved guides converge.
• Empty asset manifests archive dropped assets; already-archived records are skipped by the shared planner so pmdocs plan and server agree.
• Manual-edit protection detects CMS edits to synced title, description, navTitle, or order and returns 409 manual_edit_conflict with current_fields_hash_mismatch.
• Docs-set sync bookkeeping records sync.lastSyncedAt and sync.lastStatus without publishing admin drafts or creating a docs-set version; only the first --publish sync of a never-published set publishes it.

Read Visibility

Shared visibility helpers govern draft and archive status across llms, sitemap, marketing blocks, and route reads.

• payload/visibility owns raw-record and resolved-record visibility: getPayloadDraftStatus, isVisibleToReader, getDocsRecordLifecycleStatus, notArchivedWhere, and publishedWhere.
• llms.txt, llms-full.txt, sitemap, and the route adapter use shared visibility helpers so draft docs and draft docs sets are not served on public surfaces.
• Marketing CTA and hero afterRead hydration no longer hydrates content from unpublished docs or docs sets.
• Sidebar queries select only nav and visibility fields instead of full markdown bodies; sidebar output is unchanged.

Native CLI

pmdocs CLI enforces credential safety, server contract limits, route collision reporting, package walk reporting, and protocol parity.

• push requires https endpoints unless the host is loopback or --allow-insecure-http is set, preventing credential leakage over plain http.
• keygen writes the private key through mkstemp/O_EXCL at 0600 and warns when the key is readable by other users.
• validate, manifest, and plan enforce the server's maxBodyBytes limit before push.
• validate/manifest/plan report route collisions and preserve server failure details: issues, routeCollisions, and conflicts.
• Docs and skills walks report every skipped path; .git and node_modules are ignored at any depth; build, dist, and .next only directly below the walked root; non-UTF-8 files are rejected.
• plan and validate accept --route-base and --asset-route-base; plan can match publish state and existing assets.

Plugin Config

Plugin configuration supports apps without media collections and adds access, trust, and migration exports.

• Media upload and relationship fields are pruned when the app lacks a media collection; heroes and blocks route generated fields through pruneUploadRelations.
• PayloadMarkdownDocsConfig adds access, access.admin, per-collection access overrides, and endpoint trustForwardedHeaders; PayloadMarkdownDocsAccessConfig is exported.
• docsSetsCollectionSlug is optional for per-docs-set access scoping.
• package.json adds a ./migrations export for prepareDocsSyncMigration.

Routing and Links

Route derivation and Markdown link resolution are centralized and shared across HTML, llms, sitemap, and admin.

• routing/docsSetRoutes.ts owns docs group and docs-set route derivation with parent-chain walking, cycle detection, and slug requirements.
• routing/docsLinks.ts resolves relative and docs-root Markdown links for both the HTML page renderer and llms-full.txt.
• The link rewriter never rewrites link syntax inside code fences or inline code spans; it handles linked images and parentheses.
• Sitemap URLs percent-encode route segments; plain ASCII slugs are unchanged and already-encoded segments are not double-encoded.
• The Next route adapter uses DocsSetLookup to cache docs groups and visible docs sets per request.

Release Tooling

Release AI pipeline adds provider flexibility, changelog validation, and hardened workflows.

• Adds DeepSeek ds-flash provider support using OpenAI transport, DeepSeek base URL, and DeepSeek API key environment resolution.
• AI pipeline stage config accepts per-stage provider and base_url so emergency triage, triage, draft, polish, and release notes can override pipeline provider and URL.
• Changelog validation rejects a stale top entry whose trailer date predates the baseline tag; explicit-tag guard refuses an empty release range.
• Release workflow pins actions to commit SHAs, scopes permissions, runs meson test --print-errorlogs, and passes release AI profile and DeepSeek key env vars.
• Build/Test CI gates on lint, dev-app typecheck, Postgres-backed tests, Playwright e2e, and a consumer smoke run.

Packaging

Packaging updates cover Homebrew, Meson, Debian, and peer dependency installation for the CLI and host app.

• Homebrew formula builds with -Dinstall_skill_data=true -Dcompanion_skill_data=auto and tests pmdocs doctor and skill install dry-run.
• Meson minimum is >=1.3.0 and Debian Build-Depends match, fixing the cpp_std comma fallback requirement.
• payload-markdown and plugin-seo are peer dependencies installed in the host app; consumer smoke verifies single dependency copies, import-map resolution, next build, and pmdocs push rendering.
• The npm package remains runtime integration only; the native pmdocs CLI is installed separately.

Docs Contract

The 1.1 upgrade guide and author-facing docs cover manifest, frontmatter, CLI, and publishing contracts.

• Upgrade guide covers peer dependencies, import-map regeneration, additive schema changes, and the prepareDocsSyncMigration flow for the unique nonce index.
• Manifest validation rejects derived route segments with ?, #, or control characters; enforces maxBodyBytes; rejects route collisions; confines asset routes.
• Frontmatter rules allow decimal and 0x/0o/0b order values, prefer - item lists, require alphanumeric slug starts, warn on empty title, and reject block scalars on known fields.
• CLI docs cover doctor degraded status, validate exclusion reporting, and plan --publish, --existing-assets, and --route-base.
• Bundled Claude and Codex skill references align frontmatter forms, route-collision troubleshooting, skipped/hidden file reporting, and --route-base usage with shared contract vectors.

Tests

Shared contract vectors, characterization snapshots, and regression coverage pin sync, assets, CLI, and packaging behavior.

• contracts/vectors/*.json contract version 1 pins frontmatter, manifests, signing, titles, asset routes, content types, and limits for the TypeScript server and C++ pmdocs.
• Postgres-gated characterization snapshots pin exact llms.txt/llms-full.txt, sitemap, nav, route resolution, skills, docs-set manager data, and sync responses.
• Regression tests cover nonce migration cleanup, credential scoping, nonce replay, asset serving policy, draft visibility, manual-edit conflicts, route release, and atomic apply failures.
• CLI tests cover keygen permissions, body-size limits, route collisions, package walk reporting, OIDC options, and plan flags.