@kangentic/branding 2.0.0

package/README.md

@@ -0,0 +1,110 @@
+# Kangentic Branding
+
+Single source of truth for ALL Kangentic content assets - the icon, the
+mascot, and the social image - consumed by the website (kangentic.com),
+the desktop app, and the mobile app. Content changes here, version bumps,
+consumers update - never edit an asset inside a consumer repo.
+
+## Versioning
+
+The package major tracks the brand generation (semver):
+
+- **v1 - blue K (2025)**: the original blue disc K. Frozen verbatim in
+  `archive/v1/` (app icon ladder + ICO/ICNS in `app/`, website logo and
+  favicons in `web/`) so the brand's history and progression stay
+  comparable. Never regenerated, never edited.
+- **v2 - Warm Craft (2026)**: the current line. Cream, ink, rust, amber;
+  the two-tier mark below. Minor/patch bumps for refinements within the
+  line; the next full rebrand becomes v3 and this line moves to
+  `archive/v2/` first (the `/release` skill enforces it).
+
+## The mark (v2): a two-tier system
+
+| Asset | Mark | Use |
+|-------|------|-----|
+| `assets/brandmark-small.svg` | F4k board glyph knockout: three column holes through the rust disc, amber card mid-drop (letterless) | **THE APP ICON** (taskbar, dock, favicons, tray, stores) and in-page marks at nav/header size |
+| `assets/brandmark.svg` | Card-K knockout: rust disc, card-shaped alpha hole, floating rust K with severed amber arm-tip | Large in-page/marketing display only (hero, social, print) |
+| `assets/brandmark-filled.svg` | Card-K with the card painted cream (fixed appearance) | Large display on unknown grounds |
+
+The tier is picked by DISPLAYED size, never raster resolution - a 1024px
+app icon still renders at taskbar/dock size, so every icon raster is F4k.
+Both marks are knockouts (true alpha holes, the page or OS theme flows
+through) and share the "holes in the rust disc" DNA. The split exists
+because at small display the card-K fails structurally (the rust K merges
+with the rust ring); the letterless board glyph won the live in-header
+review. Full rationale, geometry, and decision history:
+`.claude/skills/icon-drafting/SKILL.md`.
+
+## The production tree: `resources/`
+
+Everything each surface ships, generated by `npm run gen:icons`, two-tier
+by displayed context (card-K where the mark shows large, F4k where the OS
+shows it small):
+
+- **`resources/desktop/`** - Electron set: `icon.ico` (16-256),
+  `icon.icns` (16-1024), the full PNG ladder. Tiered per entry - the OS
+  pulls card-K at 128+ (dock, Finder-large) and F4k at 16-64 (taskbar).
+- **`resources/web/`** - favicons (F4k), apple-touch + manifest squares
+  (F4k, opaque cream), `logo.png` (card-K, shown large in search), both
+  brandmark SVGs
+- **`resources/mobile/`** - iOS App Store 1024, Play Store 512, Android
+  adaptive layers. All F4k: these are single masters the OS downscales to
+  the small installed icon, so card-K would shrink to an illegible mini-K.
+
+Per-file tables and the exact per-surface mark: `resources/README.md`.
+`resources/preview.png` shows the desktop tier boundary on light and dark.
+
+## The mascot: the Overseer
+
+A separate asset from the brandmark, by design (mascot = personality, icon
+= app identity). A soft amber pixel blob with three sparkle eyes, authored
+as an ASCII map and rendered to a crisp rect-grid SVG by the shared sprite
+engine (`scripts/lib/sprite.mjs`).
+
+- `assets/mascot/overseer.svg` - the canonical inline mascot (amber on
+  transparency, theme-agnostic). `npm run gen:sprites`.
+- `resources/social/og-image.png` (1200x630) - the share image: pixel
+  wordmark + the Overseer, no font dependency. `npm run gen:og`.
+- `exploration/mascot/` - alternates and retired poses (kangaroo, board
+  creature, rust Overseer). Full rationale and decision history:
+  `.claude/skills/sprite-drafting/SKILL.md`.
+
+Every rejected creature round and the superseded mascot-based icon sets
+are frozen in `archive/mascot-explorations/` so the progression is never
+lost.
+
+## Regenerating
+
+```bash
+npm install
+npm run gen        # exploration sheets + canonical assets/
+npm run gen:icons  # production resources/
+```
+
+All geometry lives in `scripts/lib/mark.mjs` (the K is frozen path data -
+no font dependency at render time). Generated output is committed; the
+release pipeline fails if committed assets drift from the harness.
+
+## Consuming
+
+Preferred: npm - `npm install @kangentic/branding`, copy or import from
+`node_modules/@kangentic/branding/{assets,resources}/`. A git submodule
+also works if a consumer can't take an npm dependency, with the usual
+submodule pointer-bump caveats.
+
+## Releasing
+
+`/release [patch|minor|major]` in Claude Code: determinism gate (regenerate
++ verify no drift), version bump, changelog, tag, GitHub release, npm
+publish. Major bumps are reserved for brand generations and require
+archiving the outgoing line.
+
+## Migration status
+
+Moved here: the brandmark geometry + harness, canonical marks, the
+production icon tree, v1 archive. Still in consumer repos, migrating during
+the production build-out: mascot sprite pipeline (`gen-sprites.mjs`), OG
+image builder (`gen-brand.mjs`) - both in kangentic.com `scripts/` - and
+the Warm Craft exploration history in the app repo's `resources/rebrand/`.
+kangentic.com's copy of `gen-brandmark.mjs` is slated for removal; do not
+evolve geometry there.

package/assets/brandmark-filled.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512"><circle cx="256" cy="256" r="256" fill="#c0562f"/><g transform="scale(5.12)"><g transform="translate(50,50) scale(1.1014796117174366) translate(-50,-51.34228515625)"><rect x="22.009765625" y="18.6845703125" width="55.98046875" height="65.3154296875" rx="7.5" fill="#fdfbf7"/><mask id="kg33"><rect x="-50" y="-50" width="200" height="200" fill="#fff"/><rect x="53.5" y="25.9" width="4.5" height="26" transform="rotate(-38 55.75 38.9)" fill="#000"/></mask>
+    <g mask="url(#kg33)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#c0562f"/></g></g><clipPath id="kt34"><polygon points="-188.74156593464818,-277.68953976217153 303.7876143258784,352.71906312320607 618.9919157685672,106.45447299294278 126.46273550804062,-523.9541298924348"/></clipPath>
+    <g clip-path="url(#kt34)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#e8a33d"/></g></g></g></g></svg>

package/assets/brandmark-small.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512">
+    <defs><mask id="m">
+      <circle cx="256" cy="256" r="256" fill="#fff"/>
+      <g transform="scale(5.12)"><g transform="translate(-9,-9) scale(1.18)"><rect x="27" y="25" width="12.5" height="44" rx="3" fill="#000"/>
+            <rect x="43.5" y="25" width="12.5" height="24" rx="3" fill="#000"/>
+            <rect x="60" y="25" width="12.5" height="44" rx="3" fill="#000"/></g></g>
+    </mask></defs>
+    <circle cx="256" cy="256" r="256" fill="#c0562f" mask="url(#m)"/>
+    <g transform="scale(5.12)"><g transform="translate(-9,-9) scale(1.18)"><rect x="43.5" y="55" width="12.5" height="14" rx="3" fill="#e8a33d"/></g></g>
+  </svg>

package/assets/brandmark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512">
+    <defs><mask id="m">
+      <circle cx="256" cy="256" r="256" fill="#fff"/>
+      <g transform="scale(5.12)"><g transform="translate(50,50) scale(1.1014796117174366) translate(-50,-51.34228515625)"><rect x="22.009765625" y="18.6845703125" width="55.98046875" height="65.3154296875" rx="7.5" fill="#000"/></g></g>
+    </mask></defs>
+    <circle cx="256" cy="256" r="256" fill="#c0562f" mask="url(#m)"/>
+    <g transform="scale(5.12)"><g transform="translate(50,50) scale(1.1014796117174366) translate(-50,-51.34228515625)"><mask id="kg31"><rect x="-50" y="-50" width="200" height="200" fill="#fff"/><rect x="53.5" y="25.9" width="4.5" height="26" transform="rotate(-38 55.75 38.9)" fill="#000"/></mask>
+    <g mask="url(#kg31)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#c0562f"/></g></g><clipPath id="kt32"><polygon points="-188.74156593464818,-277.68953976217153 303.7876143258784,352.71906312320607 618.9919157685672,106.45447299294278 126.46273550804062,-523.9541298924348"/></clipPath>
+    <g clip-path="url(#kt32)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#e8a33d"/></g></g></g></g>
+  </svg>

package/assets/mascot/overseer.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 18 12" width="18" height="12" shape-rendering="crispEdges" role="img" aria-label="Pixel-art Kangentic mascot"><rect x="5" y="0" width="8" height="1" fill="#e8a33d"/><rect x="3" y="1" width="12" height="1" fill="#e8a33d"/><rect x="2" y="2" width="14" height="1" fill="#e8a33d"/><rect x="2" y="3" width="2" height="1" fill="#e8a33d"/><rect x="4" y="3" width="1" height="1" fill="#24201b"/><rect x="5" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="6" y="3" width="2" height="1" fill="#e8a33d"/><rect x="8" y="3" width="1" height="1" fill="#24201b"/><rect x="9" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="10" y="3" width="2" height="1" fill="#e8a33d"/><rect x="12" y="3" width="1" height="1" fill="#24201b"/><rect x="13" y="3" width="1" height="1" fill="#fdfbf7"/><rect x="14" y="3" width="2" height="1" fill="#e8a33d"/><rect x="2" y="4" width="2" height="1" fill="#e8a33d"/><rect x="4" y="4" width="2" height="1" fill="#24201b"/><rect x="6" y="4" width="2" height="1" fill="#e8a33d"/><rect x="8" y="4" width="2" height="1" fill="#24201b"/><rect x="10" y="4" width="2" height="1" fill="#e8a33d"/><rect x="12" y="4" width="2" height="1" fill="#24201b"/><rect x="14" y="4" width="2" height="1" fill="#e8a33d"/><rect x="0" y="5" width="18" height="1" fill="#e8a33d"/><rect x="0" y="6" width="18" height="1" fill="#e8a33d"/><rect x="2" y="7" width="14" height="1" fill="#e8a33d"/><rect x="2" y="8" width="14" height="1" fill="#e8a33d"/><rect x="3" y="9" width="12" height="1" fill="#e8a33d"/><rect x="4" y="10" width="2" height="1" fill="#e8a33d"/><rect x="8" y="10" width="2" height="1" fill="#e8a33d"/><rect x="12" y="10" width="2" height="1" fill="#e8a33d"/><rect x="4" y="11" width="2" height="1" fill="#e8a33d"/><rect x="8" y="11" width="2" height="1" fill="#e8a33d"/><rect x="12" y="11" width="2" height="1" fill="#e8a33d"/></svg>

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@kangentic/branding",
+  "version": "2.0.0",
+  "description": "Kangentic brand assets: the two-tier brandmark (card-K / F4k board glyph), icon sets, and the drafting harness that generates them. Single source of truth for the website, desktop app, and mobile app.",
+  "type": "module",
+  "files": [
+    "assets",
+    "resources"
+  ],
+  "scripts": {
+    "gen": "node scripts/gen-brandmark.mjs",
+    "gen:icons": "node scripts/gen-icons.mjs",
+    "gen:sprites": "node scripts/gen-sprites.mjs",
+    "gen:og": "node scripts/gen-og.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kangentic/branding.git"
+  },
+  "license": "AGPL-3.0-only",
+  "devDependencies": {
+    "sharp": "^0.34.0"
+  }
+}

package/resources/README.md

@@ -0,0 +1,41 @@
+# Kangentic brand resources (v2, Warm Craft)
+
+TWO-TIER APP ICON, keyed to displayed context (not raster resolution):
+**card-K** (the letter, with the amber tip) where the mark shows large,
+**F4k** (the board glyph) where the OS shows it small. The dividing line
+is whether the OS picks a size-specific entry or downscales one master:
+
+- Multi-resolution containers (.ico/.icns) and the desktop PNG ladder
+  tier per entry - card-K at 128+, F4k at 16-64.
+- Single-image masters the OS shrinks to chrome (store icons, PWA/
+  apple-touch/manifest icons, favicons) stay F4k, so the small installed
+  icon never becomes an illegible downscaled card-K.
+
+Generated by `npm run gen:icons` - regenerate, never hand-edit. Knockout
+renditions carry true alpha holes (the theme or wallpaper shows through,
+like the v1 blue K did). See `preview.png` for the desktop tier boundary.
+
+## desktop/ (kangentic, Electron)
+| File | Use | Mark |
+|------|-----|------|
+| icon.ico | Windows app icon (taskbar, title bar, installer); 16-256 | tiered per entry |
+| icon.icns | macOS dock / Finder; 16-1024 | tiered per entry |
+| icon.png + icon-{16..1024}.png | Linux / BrowserWindow ladder | F4k <=64, card-K >=128 |
+
+## web/ (kangentic.com)
+| File | Use | Mark |
+|------|-----|------|
+| favicon.ico, favicon-16x16.png, favicon-32x32.png | browser tabs | F4k |
+| apple-touch-icon.png (180) | iOS home-screen bookmark | F4k (opaque square) |
+| icon-192.png, icon-512.png | site.webmanifest | F4k (opaque square) |
+| logo.png (512) | JSON-LD publisher logo (shown large in search) | card-K |
+| brandmark-small.svg | in-page mark at nav/header sizes | F4k |
+| brandmark.svg | in-page mark at hero/social scale | card-K |
+
+## mobile/ (kangentic-mobile, Expo)
+| File | Use | Mark |
+|------|-----|------|
+| ios-appstore-1024.png | App Store master (downscales to the home-screen icon) | F4k (opaque, unrounded) |
+| android-playstore-512.png | Play Store listing | F4k (opaque square) |
+| android-adaptive-foreground.png (432) | adaptive icon foreground; mark in the 66% safe zone | F4k |
+| android-adaptive-background.png (432) | adaptive icon background | solid cream |

package/resources/web/brandmark-small.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512">
+    <defs><mask id="m">
+      <circle cx="256" cy="256" r="256" fill="#fff"/>
+      <g transform="scale(5.12)"><g transform="translate(-9,-9) scale(1.18)"><rect x="27" y="25" width="12.5" height="44" rx="3" fill="#000"/>
+            <rect x="43.5" y="25" width="12.5" height="24" rx="3" fill="#000"/>
+            <rect x="60" y="25" width="12.5" height="44" rx="3" fill="#000"/></g></g>
+    </mask></defs>
+    <circle cx="256" cy="256" r="256" fill="#c0562f" mask="url(#m)"/>
+    <g transform="scale(5.12)"><g transform="translate(-9,-9) scale(1.18)"><rect x="43.5" y="55" width="12.5" height="14" rx="3" fill="#e8a33d"/></g></g>
+  </svg>

package/resources/web/brandmark.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512">
+    <defs><mask id="m">
+      <circle cx="256" cy="256" r="256" fill="#fff"/>
+      <g transform="scale(5.12)"><g transform="translate(50,50) scale(1.1014796117174366) translate(-50,-51.34228515625)"><rect x="22.009765625" y="18.6845703125" width="55.98046875" height="65.3154296875" rx="7.5" fill="#000"/></g></g>
+    </mask></defs>
+    <circle cx="256" cy="256" r="256" fill="#c0562f" mask="url(#m)"/>
+    <g transform="scale(5.12)"><g transform="translate(50,50) scale(1.1014796117174366) translate(-50,-51.34228515625)"><mask id="kg31"><rect x="-50" y="-50" width="200" height="200" fill="#fff"/><rect x="53.5" y="25.9" width="4.5" height="26" transform="rotate(-38 55.75 38.9)" fill="#000"/></mask>
+    <g mask="url(#kg31)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#c0562f"/></g></g><clipPath id="kt32"><polygon points="-188.74156593464818,-277.68953976217153 303.7876143258784,352.71906312320607 618.9919157685672,106.45447299294278 126.46273550804062,-523.9541298924348"/></clipPath>
+    <g clip-path="url(#kt32)"><g transform="translate(20.68359375,5.7485651397705055) scale(0.79)"><path d="M8.0078125,22.70380401611328L23.779296875,22.70380401611328 23.779296875,55.80927276611328 24.0234375,55.80927276611328 24.365232467651367,55.05243682861328 24.804685592651367,54.14911651611328 25.341794967651367,53.09931182861328 25.9765625,51.90302276611328 45.3125,22.70380401611328 64.111328125,22.70380401611328 39.697265625,56.10224151611328 66.2109375,92.72333526611328 46.2890625,92.72333526611328 25.87890625,62.30341339111328 25.543212890625,61.73273468017578 25.1220703125,60.89960479736328 24.615478515625,59.80402374267578 24.0234375,58.44599151611328 23.779296875,58.44599151611328 23.779296875,92.72333526611328 8.0078125,92.72333526611328 8.0078125,22.70380401611328z" fill="#e8a33d"/></g></g></g></g>
+  </svg>