[aicayzer]

Summary

Rewrites the pages the marfa v0.0.54 docs issues name: read-only types at connector registration and the read_only item field, the type-conflict report for a shipped type, exception reports that need only the PostHog settings with OTEL_SDK_DISABLED, and the connector quiet-run guidance.

Closes #782, closes #785, closes #789, closes #784.

Changes

• run/telemetry.mdx: exception reports need only MARFA_POSTHOG_HOST and MARFA_POSTHOG_PROJECT_TOKEN; OTEL_SDK_DISABLED turns off traces, logs and exceptions; the https host rule and its start warning; error_reporting_enabled stops reports and notices without a restart.
• build/connector-pull-and-push.mdx was over the guide limit once the new sections went in, so it is now two guides: build/connector-pull.mdx ("Pull from a vendor", with "Keep a quiet run light" and "Declare the types you don't carry back") and build/connector-push.mdx ("Carry changes back"). Every link to the old page, and build/meta.json, now name the new pages.
• (start)/connectors.mdx: a connector says which types it holds read only, and items read read_only: true.
• run/upgrade.mdx: new section "Types a new build leaves in conflict" (conflicts in GET /types, the start warning, the refused re-registration and the fix).
• catalog/(types)/type-rules.mdx: links a parent change from a new build to that section.

Testing

pnpm test passes except sync-changelog.test.ts, which fails in this sandbox for want of network and is unrelated. The content lint checks every link and anchor. Facts checked against conformance/spec/ (items/read-only-*, connectors/read-only-types-*, types/conflict-*, instance/telemetry-*) and openapi.json at v0.0.54.

Notes for reviewers

The old address /build/connector-pull-and-push gets no redirect. #794 stays open: the kit does not yet send read_only_types (withmarfa/marfa-connectors#331 is a draft), so the guide documents the registration field and says the kit does not declare it. #793 stays open: withmarfa/marfa#2602 is not in v0.0.54.

Checklist

• The title is a scoped Conventional Commit.
• New behavior has a test that was seen failing first, or no test was needed and the reason is above.
• Docs, comments and the contract still say what is true after this change.

---

Generated by Claude Code