feat: #1 Production assets layout (src, build, Pages CDN)

.github/workflows/pages.yml

@@ -0,0 +1,49 @@
+name: Publish Pages catalog
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: pages-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+        with:
+          version: 11.22.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm validate
+      - run: pnpm test
+      - run: pnpm build
+        env:
+          CI: "true"
+      - uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  release:
+    if: "${{ github.event_name == 'workflow_dispatch' || !startsWith(github.event.head_commit.message, 'chore: Release') }}"
+    runs-on: ubuntu-latest
+    name: release-it
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+        with:
+          version: 11.22.0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+          cache: pnpm
+          # Do NOT set registry-url — breaks OIDC Trusted Publishing.
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Upgrade npm for OIDC publish
+        run: |
+          set -euo pipefail
+          # Trusted Publishing needs npm ≥ 11.5.1; pin exact to avoid range drift.
+          npm install -g npm@11.5.1
+          npm --version
+          for npmrc in "$PWD/.npmrc" "$(npm config get userconfig)" "$(npm config get globalconfig)"; do
+            if [[ -f "$npmrc" ]] && grep -qE 'always-auth|^//registry\.npmjs\.org|_authToken' "$npmrc"; then
+              # Do not print file contents — they may contain credentials.
+              echo "Refusing to publish with an auth .npmrc: $npmrc" >&2
+              exit 1
+            fi
+          done
+
+      - name: Configure git identity
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GIT_AUTHOR_NAME: github-actions[bot]
+          GIT_AUTHOR_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+          GIT_COMMITTER_NAME: github-actions[bot]
+          GIT_COMMITTER_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com
+        run: |
+          set -euo pipefail
+          git remote set-url origin \
+            "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git fetch origin main --tags
+          git checkout -B main origin/main
+          # Do not retry blindly: commit/tag may already exist if a later step failed.
+          pnpm release:ci

.github/workflows/validate.yml

@@ -0,0 +1,45 @@
+name: Validate assets
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
+        with:
+          version: 11.22.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm validate
+      - run: pnpm test
+      - run: pnpm build
+        env:
+          CI: "true"
+      - name: Ensure build did not modify sources
+        run: |
+          git diff HEAD --exit-code
+          unexpected_files="$(git ls-files --others --exclude-standard)"
+          if [[ -n "$unexpected_files" ]]; then
+            printf 'Build created unexpected files:\n%s\n' "$unexpected_files" >&2
+            exit 1
+          fi
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: asset-catalog-${{ github.sha }}
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14

.gitignore

@@ -1 +1,5 @@
 node_modules/
+dist/
+.DS_Store
+*.log
+.tmp/

.nvmrc

@@ -0,0 +1 @@
+22.16.0

.release-it.js

@@ -0,0 +1,44 @@
+/**
+ * @typedef {import('release-it').Config} ReleaseItConfig
+ * @type {ReleaseItConfig}
+ */
+export default {
+  git: {
+    commitMessage: "chore: Release v${version}\n\n[skip ci]",
+    tagName: "${version}",
+    requireBranch: "main",
+    requireCleanWorkingDir: true,
+    commit: true,
+    push: true,
+    tag: true,
+  },
+  npm: {
+    publish: true,
+    skipChecks: true, // required for OIDC — npm whoami fails without a static token
+  },
+  hooks: {
+    "before:release": "pnpm validate && pnpm test && pnpm build",
+  },
+  github: {
+    release: true,
+    releaseName: "v${version}",
+    /**
+     * @param {{ changelog?: string, version: string, name: string }} ctx
+     */
+    releaseNotes({ changelog, version, name }) {
+      const notes = (changelog ?? "").trim();
+      const npmUrl = `https://www.npmjs.com/package/${name}/v/${version}`;
+      return `${notes}\n\n📦 [\`${name}@${version}\`](${npmUrl})\n`;
+    },
+  },
+  plugins: {
+    "@release-it/conventional-changelog": {
+      infile: "CHANGELOG.md",
+      preset: {
+        name: "conventionalcommits",
+        compareUrlFormat:
+          "{{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}",
+      },
+    },
+  },
+};

AGENTS.md

@@ -0,0 +1,43 @@
+# Agent working agreements — InkAds assets
+
+Cross-agent instructions for work in `poc-inkads-assets`.
+
+## Scope
+
+This repo owns **InkAds product mark binaries** (SVG masters + generated
+favicons / rasters / OG). It is not the Singleton SD company assets package
+(`@singleton-sd/assets`).
+
+## Source of truth
+
+- Edit masters under `src/` only.
+- Do not hand-edit `dist/`.
+- Keep root `svg/` in sync with `src/` via `npm run sync:legacy-svg` (jsDelivr /
+  marketing pin compatibility until consumers move to Pages CDN).
+
+## Commits / PRs
+
+- Branch from latest `origin/main` in a dedicated worktree:
+  `feat/<issue>-<kebab-title>` (or `fix/` / `docs/`).
+- Prefer conventional commits with the GitHub issue: `feat: #1 …`.
+- Open a PR for human review; do not merge.
+
+## Build / verify
+
+```sh
+pnpm install
+pnpm validate
+pnpm test
+pnpm build
+```
+
+CI must leave `src/` and `svg/` unchanged (`git diff` clean after build).
+Releases use Trusted Publishing (OIDC) via `.github/workflows/release.yml`
+(`pnpm release:ci`) — no long-lived `NPM_TOKEN`.
+
+## Related
+
+- [BRAND.md](BRAND.md)
+- [docs/logo-asset-workflow.md](docs/logo-asset-workflow.md)
+- Issue [#1](https://github.com/singleton-sd/poc-inkads-assets/issues/1)
+- Company blueprint: `singleton-sd/design-system/assets`

BRAND.md

@@ -0,0 +1,50 @@
+# Brand assets — InkAds
+
+Source of truth for **InkAds logo / favicon / OG binaries** is this package
+(`@singleton-sd/inkads-assets`). Parent brand: [Singleton SD](https://singletonsd.com).
+
+Public catalog: [assets.inkads.poc.singletonsd.com](https://assets.inkads.poc.singletonsd.com)
+(`config/product.json` → `publicUrl`).
+
+Token **values** should align with `@singleton-sd/tokens` semantic yellows/grays
+when the product adopts the design-system package; until then the hex values in
+`meta.json` are authoritative for these masters.
+
+## Formats
+
+- **SVG** — preferred for web UI. Masters live under `src/`.
+- **PNG** — favicons, app icons, lockup rasters, OG cards. Generated into `dist/` by `npm run build`.
+
+## Roles (design doc 3a–3e)
+
+| Role | Path | Typical use |
+| --- | --- | --- |
+| Icon (3a) | `src/logo/sources/{dark,light,mono,favicon}.svg` | Nav mark, app icon, e-paper mono |
+| Horizontal lockup (3b) | `src/logo/wordmark/sources/lockup-horizontal/` | Headers / wide UI |
+| Stacked lockup (3c) | `src/logo/wordmark/sources/lockup-stacked/` | Centered / square |
+| Wordmark (3d) | `src/logo/wordmark/sources/wordmark/` | Text + refresh lines only |
+| Mono (3e) | `src/logo/sources/mono.svg` and `src/logo/wordmark/sources/lockup-horizontal/mono.svg` | E-paper / single-ink |
+
+## Usage
+
+- Do not stretch. Keep aspect ratio.
+- Clear space ≈ mark height.
+- Yellow-dark (`#FFB300`) on black; yellow-light (`#C89200`) on white.
+- Use `favicon` / 16px simplified mark for browser favicons.
+- Lockup SVGs still contain `<text>` (Open Sauce Sans). Browsers render them;
+  CI PNG rasterization may fall back to a system font until text is outlined.
+
+## Layout
+
+```text
+src/logo/sources/                 # icon masters
+src/logo/wordmark/sources/…       # lockups + wordmark
+src/og-image/{dark,light}/        # 1200×630 social cards
+svg/                              # legacy jsDelivr paths (synced from src)
+dist/                             # build output (Pages CDN) — do not edit
+```
+
+## Related
+
+- Blueprint: GitLab `@singleton-sd/assets`
+- Consumer: [poc-inkads-marketing](https://github.com/singleton-sd/poc-inkads-marketing)

CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) Singleton SD. All rights reserved.
+
+This software is proprietary to Singleton SD. The package is published to the
+public npm registry so Singleton SD products and PoC consumers can install a
+versioned artifact. Publication does not grant an open-source license.
+
+You may install and use this package only as part of Singleton SD work or with
+express written permission from Singleton SD. You may not redistribute,
+sublicense, or sell this software, or use it to create a competing product,
+except as permitted in writing by Singleton SD.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.