/linking-and-schema

name: linking-and-schema
description: >
  Generate an internal-linking plan and JSON-LD structured data from a brand's topical
  map and entity profile. Use whenever the user asks about internal links, anchor text,
  site structure, linking strategy, schema markup, structured data, or JSON-LD — or right
  after new content is drafted or published. Produces an actionable link checklist (with
  varied anchors) and validated per-node schema files. Triggers on linking/schema intent
  broadly.

linking-and-schema

Turn the map into a link graph and structured data. Both outputs are deterministic and carry the framework's fact discipline: laterals are justified (not sprayed), anchors are varied (not exact-match spam), and schema never states an ungrounded fact.

Read first: `../../framework/internal-linking-rules.md`, `../../framework/schema-jsonld.md`, `../../framework/eeat-signals.md`.

Preconditions

• `topical-map.json` and `entity-profile.json` for the brand.
• Optional: map embeddings (for lateral justification) and crawl data (for real orphans).

Workflow

1. **Internal-linking plan:**

   python ../../scripts/linking_plan.py --map brands/<slug>/topical-map.json \
     [--vecs brands/<slug>/data/embeddings/map.npz --lateral-threshold 0.72] \
     [--crawl-dir brands/<slug>/data/crawl] --brand "<Brand>" \
     --out brands/<slug>/audits/linking-plan.md

For each node it emits up/down/justified-lateral links with varied, descriptive anchors drawn from the target's query network, plus link-health flags (planned-graph orphans, over-linked hubs, and real crawl orphans if crawl data is present). Laterals below the embedding threshold are marked REVIEW rather than dropped or trusted.

2. **JSON-LD schema:**

   python ../../scripts/schema_jsonld.py --map brands/<slug>/topical-map.json \
     --entity-profile brands/<slug>/entity-profile.json \
     --locked brands/<slug>/locked-facts.json \
     --out-dir brands/<slug>/data/schema

Emits one `.jsonld` per node (HowTo / FAQPage / Product / Article), a site-level `Organization` graph, and a `checklist.md`. Product `Offer` prices come ONLY from locked facts; FAQ/HowTo answer text is left as a placeholder to be filled from the *validated* draft — so no invented answer ships in markup.

3. **Hand off:** give the user the link checklist (page → insert link → suggested anchor → where) and the schema files. Note that syntactic validation here is necessary but not sufficient — run Google's Rich Results Test before publishing.

Definition of done

• Link plan covers every node; laterals justified; orphans/over-links flagged.
• One schema file per node + org graph; 0 validation issues; no fabricated price/rating.
• Anchors are varied across placements (no exact-match repetition).

Grounding ladder

• **T0:** link plan from map structure; laterals justified by named shared attribute

(`asserted`). Schema from map + profile.

• **T1:** laterals justified by embedding distance (`derived`); real orphans from crawl.
• **Author `Person` schema** is emitted only when a real author/credential exists

(eeat-signals.md) — never fabricated to fill the template.