Sitemap / IA: mc-batch-13-general

Visual tree

Home is rendered here as the tree's root so the page has something to hang collections off of. It is a UI convenience only -- the underlying sitemap.json artifact never contains a "home" node, per skills/shopify-ia/SKILL.md ("Home is implicit, not its own sitemap node"). The node count below therefore excludes Home, matching the convention already used by projects/mc-batch-13-general (7 collections + 13 products + 2 pages = 22 nodes).

22 sitemap nodes (excludes Home)

Rationale, URL rules, multi-market architecture, internal linking

# Site Architecture Rationale — mc-batch-13-general (REAL Market Capture evidence)

This project is a downstream Build OS acceptance test: 13 REAL Amazon
products (Market Capture batch `mcbatch_0b3e7f5d59d80bb163`, captured
2026-09-07), spanning unrelated categories, with no confirmed brand and no
confirmed target market. Everything below is derived from evidence alone —
where evidence does not support a decision, that decision is marked
`UNKNOWN`/`PROPOSAL` rather than invented.

## Proposed structure

```
Home (implicit)
├── Collection: footwear (1 product)
├── Collection: headwear-caps (2 products)
├── Collection: computer-laptop-accessories (3 products)
├── Collection: party-disposable-tableware (3 products)
├── Collection: plush-toys (2 products)
├── Collection: beauty (1 product)
├── Collection: video-games (1 product)
├── Page: about
└── Page: contact
```

## Collection grouping — decision by decision

| Collection | Products (ASIN) | Why grouped together |
|---|---|---|
| `footwear` | B0B3T9JMZT (VILOCY sneakers) | Sole footwear product — no basis to merge into `headwear-caps` (different product type, department, and use case) despite both nominally being "Clothing, Shoes & Jewelry > Men" on Amazon. Amazon's own department label is NOT copied mechanically — the evidence-supported grouping principle here is product type, not raw taxonomy. |
| `headwear-caps` | B073DTZ6KZ (Flexfit cap), B0DVC5P62W (King & Fifth gym cap) | Both are men's baseball-style caps (breadcrumb: `Hats & Caps > Baseball Caps` for both); same product type, same use case (headwear), different Amazon brands — brand is explicitly NOT the grouping key. |
| `computer-laptop-accessories` | B07P619NXM (ASUS touchscreen monitor), B07Z66MK6L (USB‑C adapter), B0GFN6W8CG (Acer USB‑C hub) | All three are Electronics > Computers & Accessories evidence (breadcrumbs: `Monitors`, `Cables & Adapters`, `Docking Stations`) serving one shared use case — connecting peripherals/displays to a laptop or desktop. A monitor and a USB‑C hub are different product types, so this is a broader grouping than the others in this catalog; it is still evidence-justified (shared department + shared "computer accessory" use case), not a forced merge, and is called out explicitly as the one collection in this batch built on department-level similarity rather than product-type identity. |
| `party-disposable-tableware` | B0CLRP8PY5, B0CQL3QKP4, B0GQGPZXCD (three disposable plastic silverware sets) | All three are the SAME product type (disposable plastic cutlery sets), same breadcrumb tail (`Disposable Plates, Bowls & Cutlery`), same use case (parties/events). The strongest same-type cluster in this dataset. |
| `plush-toys` | B0CZ91RJ84 (dog plush pillow), B0FQ2HRRKL (Golden Retriever stuffed animal) | Both `Toys & Games > Stuffed Animals & Plush Toys`; same product type and audience (gifting/kids). |
| `beauty` | B0F3J6W5KW (e.l.f. blush tint) | Sole beauty product; kept as its own collection rather than merged into an unrelated one. |
| `video-games` | B0H6K928WL (GTA VI, PS5) | Sole video game; a pre-order digital-code product with a fundamentally different commerce shape (release-dated availability, no physical specifications) from everything else in the catalog — merging it anywhere else would misrepresent it. |

| Decision | Classification | Rationale |
|---|---|---|
| **Seven collections for 13 products, sized 1–3 each** | **OUR RECOMMENDED STANDARD** | This is a genuinely cross-category real-world assortment (13 different Amazon-listing brands, zero shared manufacturer/seller). Forcing fewer, broader collections (e.g. one "Accessories" catch-all) would manufacture false coherence the evidence doesn't support — the same discipline established in `demo-test-b-general`, now validated against real data instead of synthetic. |
| Collection handles are new evidence-derived slugs, not copied Amazon breadcrumb text | **OUR RECOMMENDED STANDARD** | Amazon's breadcrumb strings ("Disposable Plates, Bowls & Cutlery") are retail-taxonomy-shaped, not Shopify-collection-shaped; the collection name is a judgment call informed by the breadcrumbs, never a mechanical copy (see Part 5 instruction: do not copy Amazon taxonomy mechanically). |
| No brand/store collection or brand pages | **OUR RECOMMENDED STANDARD**, pending `brand.yaml` | `brand.name` is `null` and 13 distinct Amazon-listing brands are present with no shared ownership evidence — a "Shop by Brand" page or brand landing page would either fabricate a brand identity or imply resale/ownership relationships not in evidence. Deferred as an unresolved decision item (see below), not silently omitted. |
| No global FAQ page (yet) | **OUR RECOMMENDED STANDARD** | Per-product `content.faq_candidates` is empty for all 13 products (no confirmed inputs exist yet to derive real FAQs from — see `product.contract.yaml`'s own note that this field is a precursor, not confirmed content). Building a FAQ page now would mean inventing questions. The page slot is designed (see Part 11 in `BUILD_PLAN.md`) but not instantiated as a sitemap node until real FAQ content exists. |
| One "About" page, one "Contact" page | **OUR RECOMMENDED STANDARD** | Every store needs both regardless of catalog coherence, but — same discipline as `demo-test-b-general` — the About page cannot yet claim any brand story, since `brand.positioning` is still `NOT YET CONFIRMED`. |
| Policy pages (Shipping/Returns/Privacy/Terms), on-site Search | **SHOPIFY NATIVE CAPABILITY** | Shopify auto-provisions these; they are not Build OS sitemap nodes, same classification `demo-test-b-general` used for fixed URL prefixes. |
| No deeper subcategory nesting | **OUR RECOMMENDED STANDARD**, per the Architecture SOP's shallow-hierarchy principle | With 1–3 products per collection, there is nothing to nest yet; depth should track real catalog density, not be added preemptively. |

## What this does NOT claim

This structure does not manufacture false thematic unity across 13
Amazon-listing-brand-distinct, mostly category-distinct products. It does
not assert that any Amazon-listing brand, manufacturer, or seller found in
the evidence owns, endorses, or authorizes resale for the eventual Shopify
store. It does not invent a store brand identity, a target market, or FAQ
content that the evidence does not support.

---

## Multi-market architecture (PROPOSAL — no market evidence exists)

No market/locale signal exists anywhere in the 13 captured packages (all
are `amazon_us`). `project.yaml`'s `target_markets` is therefore `[]` and
everything in this section is a **capability demonstration**, not a
confirmed launch plan — the example market codes below (`us`, `ca`, `hk`)
are illustrative placeholders, never a claim about real target markets.

### Design principle: one Product Truth, many market renderings

Each `products/<product-id>.yaml` file stays the single canonical source of
PRODUCT facts (identity, specifications, claims, media) regardless of how
many markets the store eventually serves. A market never gets its own copy
of `product.yaml` with different facts — only its own **localized
presentation** (translated title/description, local currency/price
formatting, market-specific availability) would live in a market-scoped
content layer that does not yet exist as a Tier-1 artifact in this project
(see unresolved decision items). This is the same Single Fact Ownership
Principle `core/governance.md` already establishes for `schema_map` —
applied here to localization instead of schema mapping.

### Path-prefix structure

```
/{market}/                                   -> market home
/{market}/collections/{collection-handle}    -> localized collection listing
/{market}/collections/{collection-handle}/products/{product-handle}
                                              -> (Shopify's actual product URL nests under its collection context)
/{market}/products/{product-handle}          -> canonical/direct product URL
/{market}/pages/{page-handle}                -> about, contact
```

Concretely, for one product in this catalog, under an illustrative 3-market
launch:

```
/us/collections/footwear/products/vilocy-men-s-casual-dress-sneakers-tennis-walking-shoes
/ca/collections/footwear/products/vilocy-men-s-casual-dress-sneakers-tennis-walking-shoes
/hk/collections/footwear/products/vilocy-men-s-casual-dress-sneakers-tennis-walking-shoes
```

Same `product-handle` and same `collection-handle` in every market — only
the `{market}` path segment changes. This is deliberate: a stable handle
means one canonical identity per product/collection across every locale,
and it is what makes hreflang alternates (below) meaningful (they must
point at the same *thing*, just localized).

### Canonical / hreflang relationship

- Each market path is a **first-class, independently indexable URL** —
  `/us/...` is never a redirect wrapper around a single canonical page.
- Every localized product/collection page declares:
  - its own `<link rel="canonical">` pointing at *itself* (not at `/us/`
    universally) — each market version is canonical for its own locale,
    per current Shopify Markets / Google guidance for market-specific
    content.
  - a full set of `<link rel="alternate" hreflang="...">` tags, one per
    market the product/collection is actually published to, plus an
    `x-default` pointing at the default market (`UNKNOWN` — no default
    market is confirmed; would default to whichever market
    `project.target_markets[0]` names once populated).
- Product facts referenced by every market alternate come from the SAME
  `products/<product-id>.yaml` file — never a market-specific fork of the
  underlying facts (only the localized copy layer differs).

### What is genuinely undecided here

- Real market list (`project.target_markets` is `[]`).
- Whether `/{market}/` is realized as a Shopify Markets sub-folder
  structure (native Shopify capability) vs. multiple stores — this is a
  **SHOPIFY NATIVE CAPABILITY** decision once markets are confirmed, not
  a Build OS design choice.
- Currency display per market (`product.commerce.currency` is `USD` where
  known, `NOT YET CONFIRMED` otherwise — no multi-currency evidence
  exists).

---

## URL design rules

| Rule | Pattern | Notes |
|---|---|---|
| Product URL | `/{market}/products/{product-handle}` | `product-handle` = `slugify(product.identity.name)`, lowercase, non-alphanumeric runs collapsed to single hyphens, truncated to 60 characters, trailing hyphens stripped. Deterministic and reproducible from evidence — see `scripts/draft_products_from_evidence.py`'s `slugify()`, the same function used to produce every handle in `sitemap.json`. |
| Collection URL | `/{market}/collections/{collection-handle}` | `collection-handle` is a short, human-chosen kebab-case slug (e.g. `party-disposable-tableware`) — not mechanically derived, since collection naming is itself a judgment call (see grouping table above). |
| Handle collisions | Append the last 4 characters of the internal product-id (lowercased ASIN) if two products would otherwise slugify to the same handle, e.g. `...-cap-6w8c`. | Not needed for this batch — checked programmatically, zero collisions across all 13 real titles — but is the deterministic tie-breaker rule going forward. |
| ASIN as URL | **Never used as, or embedded in, the public-facing product URL.** | ASIN is retained only as `product.identity.asin` (internal Build OS identifier, inherited as the internal `product_id` for this batch) and inside evidence `source_refs` — never surfaced to a shopper. This matches Part 8's explicit instruction. |
| Page URL | `/{market}/pages/{page-handle}` | `about`, `contact`. |

---

## Internal linking rules

| Link | Direction | Basis |
|---|---|---|
| Breadcrumb | `Home > Collection > Product` | Every product has exactly one parent collection in `sitemap.json` (`node.parent`) — a single, unambiguous breadcrumb path, no multi-parent categorization attempted since no product in this batch evidences membership in more than one collection. |
| Collection → Product | Collection page lists every product whose `sitemap.json` node has `parent == this collection's handle`. | Direct structural fact, not a judgment call. |
| Product → Collection | "Back to {Collection Name}" / breadcrumb link, from each product page to its one parent. | Same structural fact, inverse direction. |
| Product → Related Product | Within the SAME collection only, ranked by shared `specifications.additional_properties` labels where present (e.g. both `party-disposable-tableware` products sharing a "Serves N guests" style property) — falling back to "other products in this collection" when no shared attribute exists (e.g. the two `plush-toys` products share no structured attribute beyond category, which is itself sufficient justification). Never cross-collection — nothing in evidence supports e.g. suggesting the blush tint from a sneaker product page. | Evidence-driven (attribute similarity within a category), not arbitrary SEO cross-linking. |
| Product → Brand/Store context | **Not built.** `brand.name` is `null`; there is no confirmed store brand page to link to. Amazon-listing-brand/manufacturer/seller values stay in evidence (`source_refs`), never surfaced as a storefront "visit the brand" link, since no ownership/authorization relationship is established (see Part 4 and `brand.yaml`). | Deferred — see unresolved decision items. |
| Related-content (VOC) | Product pages MAY surface `customer_insights.customers_say` topic labels (e.g. "Fit (903)") as informational "what shoppers mention" chips, clearly separated from specifications/claims. Never phrased as a product fact or a merchant claim. | See `BUILD_PLAN.md` Part 11 (Product page template) for the exact block boundary. |

---

## Decision-log cross-reference

See `decision_log/log.md` for the dated record of these decisions and the
validator runs confirming every artifact in this project passes
`validate_artifact.py` at DRAFT level.

Raw sitemap.json

{
  "artifact_type": "site_architecture",
  "sitemap": {
    "nodes": [
      {
        "handle": "footwear",
        "type": "collection"
      },
      {
        "handle": "vilocy-men-s-casual-dress-sneakers-tennis-walking-shoes",
        "parent": "footwear",
        "product_ref": "products/b0b3t9jmzt.yaml",
        "type": "product"
      },
      {
        "handle": "headwear-caps",
        "type": "collection"
      },
      {
        "handle": "flexfit-men-s-athletic-baseball-fitted-cap",
        "parent": "headwear-caps",
        "product_ref": "products/b073dtz6kz.yaml",
        "type": "product"
      },
      {
        "handle": "gym-baseball-hats-for-men-by-king-fifth-workout-hat-low-prof",
        "parent": "headwear-caps",
        "product_ref": "products/b0dvc5p62w.yaml",
        "type": "product"
      },
      {
        "handle": "computer-laptop-accessories",
        "type": "collection"
      },
      {
        "handle": "asus-vt229h-22-inch-1080p-fhd-ips-touchscreen-monitor-hdmi-v",
        "parent": "computer-laptop-accessories",
        "product_ref": "products/b07p619nxm.yaml",
        "type": "product"
      },
      {
        "handle": "basesailor-usb-to-usb-c-adapter-usbc-female-to-usb-a-male-ch",
        "parent": "computer-laptop-accessories",
        "product_ref": "products/b07z66mk6l.yaml",
        "type": "product"
      },
      {
        "handle": "acer-usb-c-hub-5-in-1-usbc-to-hdmi-adapter-with-4k-60hz-for",
        "parent": "computer-laptop-accessories",
        "product_ref": "products/b0gfn6w8cg.yaml",
        "type": "product"
      },
      {
        "handle": "party-disposable-tableware",
        "type": "collection"
      },
      {
        "handle": "goodluck-100-pack-pre-rolled-gold-plastic-silverware-wrapped",
        "parent": "party-disposable-tableware",
        "product_ref": "products/b0clrp8py5.yaml",
        "type": "product"
      },
      {
        "handle": "supernal-120-pack-silver-plastic-silverware-wrapped-cutlery",
        "parent": "party-disposable-tableware",
        "product_ref": "products/b0cql3qkp4.yaml",
        "type": "product"
      },
      {
        "handle": "90pcs-orange-plastic-silverware-set-disposable-forks-spoons",
        "parent": "party-disposable-tableware",
        "product_ref": "products/b0gqgpzxcd.yaml",
        "type": "product"
      },
      {
        "handle": "plush-toys",
        "type": "collection"
      },
      {
        "handle": "dog-plush-pillow-8inch-puppy-stuffed-animal-toy",
        "parent": "plush-toys",
        "product_ref": "products/b0cz91rj84.yaml",
        "type": "product"
      },
      {
        "handle": "golden-retriever-stuffed-animal-15-inch-medium-sized-dog-stu",
        "parent": "plush-toys",
        "product_ref": "products/b0fq2hrrkl.yaml",
        "type": "product"
      },
      {
        "handle": "beauty",
        "type": "collection"
      },
      {
        "handle": "e-l-f-sheer-for-it-blush-tint-cherry-cola",
        "parent": "beauty",
        "product_ref": "products/b0f3j6w5kw.yaml",
        "type": "product"
      },
      {
        "handle": "video-games",
        "type": "collection"
      },
      {
        "handle": "grand-theft-auto-vi-playstation-5-code-in-box-delivers-11-12",
        "parent": "video-games",
        "product_ref": "products/b0h6k928wl.yaml",
        "type": "product"
      },
      {
        "handle": "about",
        "type": "page"
      },
      {
        "handle": "contact",
        "type": "page"
      }
    ]
  },
  "status": "DRAFT"
}