[aicayzer]

Summary

Type rules now covers link_field and version_policy, and display hints move to a Catalog page of their own, Display hints, at /catalog/display-hints in the Types folder. The split gives back the details the first version of this pull request cut to stay within Type rules' limit. The Swift SDK's Server calls page names both icon sets Marfa pins, and Define a type shows the status form of a scaffold field.

This pull request is stacked on #764 and targets its branch. Once #764 merges, it retargets to main.

Changes

• Type rules: adds a Link field section (types/link-field, types/link-field-refused, items/link-taken) and a Version policy section (types/version-policy-values, types/version-policy-order, housekeeping/thinning-policy). Display hints is now a short section that links to the new page. It restores that a new compatible_with target outside the platform needs write on it, while keeping one doesn't (types/compatible-with-reach, types/compatible-with-preserved). It also restores the explanation that a natural-key upsert doesn't restart the feed window. The contract footer drops the device chapter, which only the moved sections used.
• Display hints (new): the hints table, the icon sets, inheritance, Names and previews, and The owner's icon. It restores three details:
  • Marfa doesn't check the text in body_field (types/body-markdown).
  • The owner's icon has 403 forbidden and 403 type_not_permitted (types/icon-who-refused), along with 400 invalid_schema and 404 type_not_found.
  • Devices take an icon change at their next catch-up or held stream, and no event announces it (device/catalog-icon). Deleting a type discards its icon (types/icon-deleted).
• Links: every link to /catalog/type-rules#display-hints, #names-and-previews and #the-owners-icon now points at the matching section of Display hints. These links are on Items and types, Define a type, Change a type, Pull and push, Export and restore, and the Swift SDK's Items and Server calls pages. The Types landing page names the new page.
• Wiring: the new page is in the Types meta.json, in page-limits.json as a guide (like Type rules and Field kinds), and in content/AGENTS.md. The Catalog test and the docs map test list it.
• Catalog test: a link from a Catalog page to a Reference page, such as /swift-sdk/items#names-and-previews, now resolves against the Reference group instead of failing as broken.
• Server calls (Swift SDK): the icon sentence names lucide: and simple-icons: as the two pinned Iconify sets.
• Define a type: the scaffold sentence adds NAME:status:WORD=GROUP,WORD=GROUP, checked against core/marfa-cli/COMMANDS.md.

Testing

• pnpm test passes (830 tests), including the word limits, the Catalog test and the docs map test.
• pnpm build passes. In vite preview, a crawl of every page in docs-map.md found no broken internal link or section link (117 pages).
• llms-full.txt and docs-map.md list Display hints between Type rules and Field kinds.
• I checked the changed pages at desktop width and at 375 px with device emulation (no horizontal scroll), and read the new page's .md copy.

Notes for reviewers

Every restored detail was checked against the types and device chapters on marfa's main.

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.