@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/scripts/version-bump.sh

@@ -0,0 +1,463 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+#  version-bump.sh
+#  Auto-bumps patch version (x.y.z → x.y.z+1) on a feat/* or fix/* branch,
+#  as the LAST CI step before the PR merges into integration.
+#
+#  Strategy (runs on the feature branch, not on integration):
+#    1. Must be on a feat/* or fix/* branch — not on integration itself.
+#    2. Fetches origin/integration and compares versions:
+#         Same    → PR did not manually bump → auto-bump on the feature branch.
+#         Different → developer bumped intentionally in the PR → skip silently.
+#    3. Commits + pushes the bump back to the SAME feature branch (***NO_CI***
+#       prevents a second pipeline run). The PR then merges to integration
+#       already carrying the bumped version.
+#
+#  Why not push to integration directly?
+#    Azure DevOps branch policy (TF402455) blocks direct pushes to protected
+#    branches. We never bypass this — instead we bump on the feature branch.
+#
+#  Supported manifest types — detected from filename, no scanning:
+#    package.json    → npm    (.version)
+#    pyproject.toml  → python ([project] version, uv / PEP 621)
+#    Cargo.toml      → rust   ([package] version)
+#
+#  Usage:
+#    ./scripts/version-bump.sh --file <path/to/manifest> [OPTIONS]
+#
+#  Options:
+#    -f, --file   <path>   REQUIRED. Exact path to the version manifest.
+#    -b, --branch <name>   Integration branch to compare against (default: integration)
+#        --push            Push the bump commit back to the feature branch
+#    -n, --dry-run         Print what would change; no edits, no commit
+#    -h, --help            Show this help
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# ── ANSI colours ──────────────────────────────────────────────────────────────
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+BLUE='\033[0;34m'; BOLD='\033[1m'; NC='\033[0m'
+info()  { printf "${BLUE}[INFO]${NC}  %s\n"  "$*"; }
+ok()    { printf "${GREEN}[OK]${NC}    %s\n"  "$*"; }
+warn()  { printf "${YELLOW}[WARN]${NC}  %s\n" "$*"; }
+die()   { printf "${RED}[ERROR]${NC} %s\n" "$*" >&2; exit 1; }
+step()  { printf "\n${BOLD}▶ %s${NC}\n" "$*"; }
+
+# ── State ─────────────────────────────────────────────────────────────────────
+VERSION_FILE=""
+PROJECT_TYPE=""
+GIT_REPO_ROOT=""
+CURRENT_VERSION=""
+CURRENT_BRANCH=""
+INTEGRATION_BRANCH="integration"
+DRY_RUN=false
+DO_PUSH=false
+
+# ─────────────────────────────────────────────────────────────────────────────
+usage() {
+  cat <<'HELP'
+version-bump.sh — Bump patch version (x.y.z → x.y.z+1) on a feat/fix branch before merge
+
+USAGE
+  ./scripts/version-bump.sh --file <path> [OPTIONS]
+
+OPTIONS
+  -f, --file   <path>   REQUIRED. Exact path to the version manifest:
+                          package.json   → npm
+                          pyproject.toml → python (PEP 621 / uv)
+                          Cargo.toml     → rust
+  -b, --branch <name>   Integration branch to compare against (default: integration)
+      --push            Push the bump commit back to the feature branch after committing
+  -n, --dry-run         Show what would change; do not modify or commit
+  -h, --help            Show this message
+
+GUARDS
+  1. Must be on a feat/* or fix/* branch — never runs on integration directly.
+  2. Fetches origin/<integration-branch> and compares versions:
+       Same    → PR did not manually bump the version → auto-bump.
+       Different → developer bumped intentionally in the PR → skip silently.
+
+PUSH TARGET
+  The bump commit is pushed back to the CURRENT feature branch (not integration).
+  Azure DevOps branch policies block direct pushes to integration; we never bypass them.
+
+CI SKIP
+  Bump commit message contains ***NO_CI*** — Azure DevOps' official keyword
+  to prevent the resulting push from re-triggering the pipeline.
+
+AZURE PIPELINES — add as last step in the CI job, covering PR builds on feat/* / fix/*:
+
+  - script: |
+      git config user.email "pipeline@build.com"
+      git config user.name  "Azure Pipelines"
+      git remote set-url origin \
+        "https://x-token:$(System.AccessToken)@dev.azure.com/org/project/_git/repo"
+      bash scripts/version-bump.sh --file package.json --push
+    displayName: Bump patch version
+    condition: |
+      and(
+        succeeded(),
+        or(
+          startsWith(variables['System.PullRequest.SourceBranch'], 'refs/heads/feat/'),
+          startsWith(variables['System.PullRequest.SourceBranch'], 'refs/heads/fix/'),
+          startsWith(variables['Build.SourceBranch'], 'refs/heads/feat/'),
+          startsWith(variables['Build.SourceBranch'], 'refs/heads/fix/')
+        ),
+        not(contains(variables['Build.SourceVersionMessage'], '***NO_CI***'))
+      )
+    env:
+      SYSTEM_ACCESSTOKEN: $(System.AccessToken)
+      BUILD_SOURCEBRANCH: $(Build.SourceBranch)
+      SYSTEM_PULLREQUEST_SOURCEBRANCH: $(System.PullRequest.SourceBranch)
+HELP
+  exit 0
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+parse_args() {
+  local file_given=false
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -f|--file)   VERSION_FILE="${2:?'--file requires a path'}"; file_given=true; shift 2 ;;
+      -b|--branch) INTEGRATION_BRANCH="${2:?'--branch requires a name'}"; shift 2 ;;
+      --push)      DO_PUSH=true; shift ;;
+      -n|--dry-run) DRY_RUN=true; shift ;;
+      -h|--help)   usage ;;
+      *) die "Unknown option: '$1'. Run with --help." ;;
+    esac
+  done
+  $file_given || die "--file <path> is required. Example: --file package.json"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Resolve manifest + detect type from filename (no scanning)
+# ─────────────────────────────────────────────────────────────────────────────
+resolve_manifest() {
+  step "Resolving manifest"
+  [[ -f "$VERSION_FILE" ]] || die "Manifest not found: '${VERSION_FILE}'"
+
+  # Physical absolute path (handles /tmp → /private/tmp on macOS etc.)
+  VERSION_FILE="$(cd "$(dirname "$VERSION_FILE")" && pwd -P)/$(basename "$VERSION_FILE")"
+
+  local base
+  base="$(basename "$VERSION_FILE")"
+  case "$base" in
+    package.json)   PROJECT_TYPE="npm"    ;;
+    pyproject.toml) PROJECT_TYPE="python" ;;
+    Cargo.toml)     PROJECT_TYPE="rust"   ;;
+    *) die "Unrecognised manifest '${base}'. Expected: package.json | pyproject.toml | Cargo.toml" ;;
+  esac
+
+  local file_dir
+  file_dir="$(dirname "$VERSION_FILE")"
+  GIT_REPO_ROOT="$(git -C "$file_dir" rev-parse --show-toplevel 2>/dev/null)" || \
+    die "'${VERSION_FILE}' is not inside a git repository."
+  GIT_REPO_ROOT="$(cd "$GIT_REPO_ROOT" && pwd -P)"
+
+  info "Manifest      : ${VERSION_FILE}"
+  info "Type          : ${BOLD}${PROJECT_TYPE}${NC}"
+  info "Git repo root : ${GIT_REPO_ROOT}"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Version readers
+# ─────────────────────────────────────────────────────────────────────────────
+_read_npm() {
+  node -e "const fs=require('fs'); process.stdout.write(JSON.parse(fs.readFileSync('$1','utf8')).version)"
+}
+
+_read_python() {
+  python3 - "$1" <<'PY'
+import sys, re
+text = open(sys.argv[1]).read()
+def find_in_section(pat, text):
+    in_sect = False
+    for line in text.splitlines():
+        s = line.strip()
+        if re.match(pat, s):    in_sect = True;  continue
+        if re.match(r'^\[', s): in_sect = False
+        if in_sect:
+            m = re.match(r'^version\s*=\s*["\']([^"\']+)["\']', s)
+            if m: return m.group(1)
+    return None
+ver = (find_in_section(r'^\[project\]', text)
+    or find_in_section(r'^\[tool\.poetry\]', text))
+if not ver:
+    m = re.search(r'^version\s*=\s*["\']([^"\']+)["\']', text, re.M)
+    ver = m.group(1) if m else None
+if ver: sys.stdout.write(ver); sys.exit(0)
+sys.stderr.write(f"version not found in {sys.argv[1]}\n"); sys.exit(1)
+PY
+}
+
+_read_rust() {
+  python3 - "$1" <<'PY'
+import sys, re
+in_pkg = False
+for line in open(sys.argv[1]):
+    s = line.strip()
+    if re.match(r'^\[package\]', s): in_pkg = True;  continue
+    if re.match(r'^\[', s):          in_pkg = False
+    if in_pkg:
+        m = re.match(r'^version\s*=\s*["\']([^"\']+)["\']', s)
+        if m: sys.stdout.write(m.group(1)); sys.exit(0)
+sys.stderr.write(f"[package] version not found in {sys.argv[1]}\n"); sys.exit(1)
+PY
+}
+
+get_version() {
+  local file="${1:-$VERSION_FILE}"
+  case "$PROJECT_TYPE" in
+    npm)    _read_npm    "$file" ;;
+    python) _read_python "$file" ;;
+    rust)   _read_rust   "$file" ;;
+  esac
+}
+
+get_version_at_ref() {
+  local git_ref="$1"
+  local rel_file="${VERSION_FILE#"${GIT_REPO_ROOT}/"}"
+  local tmp
+  tmp="$(mktemp)"
+  trap "rm -f '${tmp}'" RETURN
+  git -C "$GIT_REPO_ROOT" show "${git_ref}:${rel_file}" > "$tmp" 2>/dev/null || \
+    die "Cannot read '${rel_file}' at ref '${git_ref}'. Is the file committed?"
+  get_version "$tmp"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Patch bumper  x.y.z → x.y.(z+1)
+# ─────────────────────────────────────────────────────────────────────────────
+bump_patch() {
+  local core="${1%%[-+]*}"
+  local major minor patch
+  IFS='.' read -r major minor patch <<< "$core"
+  [[ "$major" =~ ^[0-9]+$ && "$minor" =~ ^[0-9]+$ && "$patch" =~ ^[0-9]+$ ]] || \
+    die "Cannot parse '${1}' as semver x.y.z"
+  echo "${major}.${minor}.$((patch + 1))"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Version writers
+# ─────────────────────────────────────────────────────────────────────────────
+_write_npm() {
+  python3 - "$1" "$2" <<'PY'
+import json, sys
+path, ver = sys.argv[1], sys.argv[2]
+d = json.load(open(path))
+d['version'] = ver
+with open(path, 'w') as f:
+    json.dump(d, f, indent=2, ensure_ascii=False); f.write('\n')
+PY
+}
+
+_write_python() {
+  python3 - "$1" "$2" <<'PY'
+import sys, re
+path, new_ver = sys.argv[1], sys.argv[2]
+lines = open(path).readlines()
+SECTIONS = [r'^\[project\]', r'^\[tool\.poetry\]']
+in_target = replaced = False
+result = []
+for line in lines:
+    s = line.strip()
+    if any(re.match(p, s) for p in SECTIONS): in_target = True
+    elif re.match(r'^\[', s):                  in_target = False
+    if in_target and not replaced:
+        new_line = re.sub(r'^(version\s*=\s*)["\']([^"\']+)["\']',
+                          lambda m: m.group(1) + '"' + new_ver + '"', line)
+        if new_line != line: replaced = True; line = new_line
+    result.append(line)
+if not replaced:
+    full = re.sub(r'^(version\s*=\s*)["\']([^"\']+)["\']',
+                  lambda m: m.group(1) + '"' + new_ver + '"',
+                  ''.join(result), count=1, flags=re.M)
+    open(path, 'w').write(full)
+else:
+    open(path, 'w').writelines(result)
+PY
+}
+
+_write_rust() {
+  python3 - "$1" "$2" <<'PY'
+import sys, re
+path, new_ver = sys.argv[1], sys.argv[2]
+lines = open(path).readlines()
+in_pkg = replaced = False
+result = []
+for line in lines:
+    s = line.strip()
+    if re.match(r'^\[package\]', s): in_pkg = True
+    elif re.match(r'^\[', s):        in_pkg = False
+    if in_pkg and not replaced:
+        new_line = re.sub(r'^(version\s*=\s*)["\']([^"\']+)["\']',
+                          lambda m: m.group(1) + '"' + new_ver + '"', line)
+        if new_line != line: replaced = True; line = new_line
+    result.append(line)
+open(path, 'w').writelines(result)
+PY
+}
+
+set_version() {
+  case "$PROJECT_TYPE" in
+    npm)    _write_npm    "$VERSION_FILE" "$1" ;;
+    python) _write_python "$VERSION_FILE" "$1" ;;
+    rust)   _write_rust   "$VERSION_FILE" "$1" ;;
+  esac
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Lock file updates (best-effort, non-fatal)
+# ─────────────────────────────────────────────────────────────────────────────
+update_lock_files() {
+  case "$PROJECT_TYPE" in
+    rust)
+      if command -v cargo &>/dev/null; then
+        info "Regenerating Cargo.lock (cargo update --workspace)…"
+        cargo update --workspace --quiet 2>/dev/null || warn "cargo update failed — Cargo.lock may be stale."
+      else
+        warn "cargo not found — Cargo.lock NOT updated."
+      fi ;;
+    python)
+      if command -v uv &>/dev/null; then
+        info "Regenerating uv.lock (uv lock)…"
+        uv lock --quiet 2>/dev/null || warn "uv lock failed — uv.lock may be stale."
+      fi ;;
+    npm)
+      warn "npm lock file NOT touched — run 'npm install' locally to regenerate." ;;
+  esac
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Guards
+# ─────────────────────────────────────────────────────────────────────────────
+validate_branch() {
+  step "Validating source branch"
+  local branch
+  branch="$(git -C "$GIT_REPO_ROOT" rev-parse --abbrev-ref HEAD)"
+
+  # Azure Pipelines checks out in detached HEAD state.
+  # In PR builds, SYSTEM_PULLREQUEST_SOURCEBRANCH gives the real source branch.
+  # In IndividualCI builds, BUILD_SOURCEBRANCH gives the branch.
+  if [[ "$branch" == "HEAD" ]]; then
+    local pr_branch="${SYSTEM_PULLREQUEST_SOURCEBRANCH:-}"
+    local ci_branch="${BUILD_SOURCEBRANCH:-${GITHUB_REF:-}}"
+    # Azure DevOps passes '$(Var.Name)' literally when the variable is undefined.
+    # Discard any value that looks like an unexpanded template.
+    [[ "$pr_branch" == '$('* ]] && pr_branch=""
+    [[ "$ci_branch"  == '$('* ]] && ci_branch=""
+    # PR build: prefer the PR source branch (not the synthetic merge ref)
+    local env_branch="${pr_branch:-$ci_branch}"
+    branch="${env_branch#refs/heads/}"
+    [[ -n "$branch" ]] || \
+      die "Detached HEAD and no branch env var set. Cannot determine branch."
+    info "Detached HEAD — branch from env: ${branch}"
+  fi
+
+  [[ "$branch" =~ ^(feat|fix)/ ]] || \
+    die "Expected a feat/* or fix/* branch, currently on '${branch}'. Version bump runs on feature branches before PR merge."
+
+  ok "On feature branch '${branch}'."
+  CURRENT_BRANCH="$branch"
+}
+
+# Guard: compare current branch version against origin/integration.
+# Same    → PR did not manually bump → auto-bump this branch.
+# Different → manual bump in PR → skip silently (exit 0).
+validate_version_unchanged() {
+  step "Comparing version against origin/${INTEGRATION_BRANCH}"
+
+  local rel_file="${VERSION_FILE#"${GIT_REPO_ROOT}/"}"
+  local v_now v_integration
+
+  v_now="$(get_version)" || die "Cannot read current version from manifest."
+
+  # Fetch latest integration so our remote tracking ref is up to date.
+  git -C "$GIT_REPO_ROOT" fetch origin "${INTEGRATION_BRANCH}" --quiet 2>/dev/null || \
+    warn "Could not fetch origin/${INTEGRATION_BRANCH} — using cached remote tracking branch."
+
+  # If the manifest doesn't exist on integration yet (new project), just bump.
+  if ! git -C "$GIT_REPO_ROOT" show "origin/${INTEGRATION_BRANCH}:${rel_file}" >/dev/null 2>&1; then
+    warn "Manifest '${rel_file}' not found on '${INTEGRATION_BRANCH}' — treating as new project; bumping."
+    CURRENT_VERSION="$v_now"
+    return
+  fi
+
+  local tmp
+  tmp="$(mktemp)"
+  trap "rm -f '${tmp}'" RETURN
+  git -C "$GIT_REPO_ROOT" show "origin/${INTEGRATION_BRANCH}:${rel_file}" > "$tmp" 2>/dev/null
+  v_integration="$(get_version "$tmp")" || die "Cannot read version from origin/${INTEGRATION_BRANCH}."
+
+  info "Version on this branch       : ${v_now}"
+  info "Version on ${INTEGRATION_BRANCH}            : ${v_integration}"
+
+  if [[ "$v_now" != "$v_integration" ]]; then
+    printf "\n${YELLOW}${BOLD}↳ Version differs (%s here vs %s on %s). Manual bump detected — skipping auto-bump.${NC}\n\n" \
+      "$v_now" "$v_integration" "$INTEGRATION_BRANCH"
+    exit 0   # clean exit — not an error
+  fi
+
+  ok "Versions match at ${BOLD}${v_now}${NC} — safe to auto-bump."
+  CURRENT_VERSION="$v_now"
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Commit  — ***NO_CI*** suppresses Azure DevOps CI on the resulting push
+# ─────────────────────────────────────────────────────────────────────────────
+commit_bump() {
+  local new_ver="$1"
+  git -C "$GIT_REPO_ROOT" add "$VERSION_FILE"
+  case "$PROJECT_TYPE" in
+    rust)   [[ -f "${GIT_REPO_ROOT}/Cargo.lock" ]] && git -C "$GIT_REPO_ROOT" add "${GIT_REPO_ROOT}/Cargo.lock" || true ;;
+    python) [[ -f "${GIT_REPO_ROOT}/uv.lock"    ]] && git -C "$GIT_REPO_ROOT" add "${GIT_REPO_ROOT}/uv.lock"    || true ;;
+  esac
+  git -C "$GIT_REPO_ROOT" commit -m "chore: bump version ${CURRENT_VERSION} → ${new_ver} ***NO_CI***"
+  ok "Committed: chore: bump version ${CURRENT_VERSION} → ${new_ver} ***NO_CI***"
+}
+
+push_bump() {
+  local remote
+  remote="$(git -C "$GIT_REPO_ROOT" remote | head -1)"
+  [[ -n "$remote" ]] || die "No git remote found — cannot push."
+  info "Pushing to ${remote}/${CURRENT_BRANCH}…"
+  git -C "$GIT_REPO_ROOT" push "$remote" "HEAD:${CURRENT_BRANCH}"
+  ok "Pushed to ${remote}/${CURRENT_BRANCH}."
+}
+
+# ─────────────────────────────────────────────────────────────────────────────
+#  Main
+# ─────────────────────────────────────────────────────────────────────────────
+main() {
+  parse_args "$@"
+  resolve_manifest
+  validate_branch
+  validate_version_unchanged   # exits 0 silently if version was manually bumped
+
+  local new_version
+  new_version="$(bump_patch "$CURRENT_VERSION")"
+
+  step "Version bump"
+  info "  ${CURRENT_VERSION}  →  ${BOLD}${new_version}${NC}"
+
+  if $DRY_RUN; then
+    warn "Dry-run — no files modified, no commit made."
+    return 0
+  fi
+
+  set_version "$new_version"
+  ok "Updated ${VERSION_FILE}"
+  update_lock_files "$new_version"
+
+  step "Committing"
+  commit_bump "$new_version"
+
+  if $DO_PUSH; then
+    step "Pushing"
+    push_bump
+  fi
+
+  printf "\n${GREEN}${BOLD}✓ Done.${NC} Version bumped to ${BOLD}%s${NC}\n\n" "$new_version"
+}
+
+main "$@"

package/spec/codex.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "codex-plugin.json",
   "title": "Codex Plugin Manifest",
-  "description": "Validates .codex-plugin/plugin.json for OpenAI Codex plugins. Matches the enact-operator plugin structure.",
+  "description": "Validates .codex-plugin/plugin.json for OpenAI Codex plugins. Based on the OpenAI Codex plugin build docs.",
   "type": "object",
   "required": [
     "name"
@@ -69,11 +69,6 @@
       "description": "Relative path to the skills directory.",
       "default": "./skills/"
     },
-    "commands": {
-      "type": "string",
-      "description": "Relative path to slash commands directory (flat Markdown files).",
-      "default": "./commands/"
-    },
     "mcpServers": {
       "type": "string",
       "description": "Relative path to the .mcp.json MCP server configuration file.",
@@ -144,11 +139,6 @@
           "description": "Human-readable list of capabilities shown in the plugin directory."
         }
       }
-    },
-    "agents": {
-      "type": "string",
-      "description": "Relative path to the agents dir.",
-      "default": "./agents/"
     }
   }
 }

package/spec/index.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "enact-extensions-index.json",
+  "title": "Enact Extensions Discovery Index",
+  "description": "Schema for the generated discovery index produced by `enact-extensions index`. This is a generated artifact (never committed). The schema file is committed as the contract.",
+  "type": "object",
+  "required": ["generatedAt", "count", "plugins"],
+  "additionalProperties": false,
+  "properties": {
+    "generatedAt": {
+      "description": "ISO 8601 timestamp when the index was generated, or null if not provided.",
+      "oneOf": [
+        { "type": "string", "format": "date-time" },
+        { "type": "null" }
+      ]
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Total number of plugin bundles discovered. Must equal plugins.length."
+    },
+    "plugins": {
+      "type": "array",
+      "description": "Ordered list of discovered plugin bundle entries.",
+      "items": {
+        "type": "object",
+        "required": ["name", "version", "category", "description", "targets", "path"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Unique plugin identifier from .agents/plugin.json."
+          },
+          "version": {
+            "type": "string",
+            "description": "Plugin version string."
+          },
+          "category": {
+            "type": "string",
+            "description": "Plugin category (from interface.category, may be empty string)."
+          },
+          "description": {
+            "type": "string",
+            "description": "Short human-readable plugin description."
+          },
+          "targets": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Agent platforms this plugin targets (e.g. claude, codex, cursor)."
+          },
+          "path": {
+            "type": "string",
+            "description": "Repo-relative path to the plugin bundle directory (relative to package root, not absolute)."
+          }
+        }
+      }
+    }
+  }
+}

package/web/assets/README.md

@@ -0,0 +1,111 @@
+# web/assets — Amsterdam Data Labs Design System
+
+## Provenance
+
+These assets are vendored from the Amsterdam Data Labs (ADL) design system,
+originally sourced from the `net-revenue-demo` repository
+(`public/_ds/amsterdam-data-labs-design-system-*/tokens/`).
+
+They are committed source — not generated — and represent the UI styling
+contract for any HTML surfaces served by enact-extensions. Do not hand-edit
+token values; update from the upstream design system and re-vendor.
+
+## Contents
+
+```
+web/assets/
+  logo-full.png          — ADL full wordmark (horizontal)
+  logo-slim.png          — ADL compact mark (icon-only / slim)
+  tokens/
+    index.css            — single entrypoint: @imports all 5 token files
+    fonts.css            — Google Fonts @import (Space Grotesk / Manrope / IBM Plex Mono)
+    colors.css           — primitive ramps (--adl-*) + semantic aliases
+    spacing.css          — 4px-grid space scale, breakpoints, z-index
+    effects.css          — radii, shadows, motion easing + duration
+    base.css             — element resets that consume the tokens above
+```
+
+Link `tokens/index.css` from HTML — it loads all five files in the correct
+dependency order (fonts → colors → spacing → effects → base).
+
+## Key Semantic Tokens
+
+Product code should consume **semantic** tokens only — never the raw `--adl-*`
+primitive ramps.
+
+### Backgrounds & Surfaces
+
+| Token | Light | Dark |
+|---|---|---|
+| `--bg-canvas` | `#ffffff` | `#061726` |
+| `--surface-default` | `#ffffff` | `--adl-navy-900` |
+| `--surface-raised` | `--adl-neutral-50` | `--adl-navy-800` |
+| `--surface-sunken` | `--adl-neutral-100` | `--adl-navy-950` |
+
+### Text
+
+| Token | Purpose |
+|---|---|
+| `--text-primary` | Body copy, headings |
+| `--text-secondary` | Supporting labels |
+| `--text-muted` | Placeholder, captions |
+| `--text-link` | Hyperlinks |
+
+### Borders
+
+| Token | Purpose |
+|---|---|
+| `--border-subtle` | Dividers, ghost cards |
+| `--border-default` | Standard input borders |
+| `--border-strong` | Emphasized outlines |
+| `--border-focus` | Keyboard focus ring |
+
+### Brand
+
+The ADL primary brand anchor is **`--adl-teal-500: #18949a`**.
+
+```css
+--brand-primary:        var(--adl-teal-500);   /* #18949a */
+--brand-primary-hover:  var(--adl-teal-600);
+--brand-primary-active: var(--adl-teal-700);
+--brand-secondary:       var(--adl-mint-400);  /* #5acfb0 */
+```
+
+## Light / Dark Theming
+
+Tokens switch automatically via the `[data-theme]` attribute. Apply it to
+`<html>` (or any subtree root) to switch the entire surface:
+
+```html
+<!-- light (default — no attribute needed) -->
+<html>
+
+<!-- dark -->
+<html data-theme="dark">
+```
+
+All semantic tokens resolve to their dark-mode equivalents when
+`[data-theme="dark"]` is in scope. Primitive ramps (`--adl-*`) are
+theme-invariant.
+
+## Typography
+
+Fonts load from Google Fonts via the `@import` in `fonts.css`. No font
+binaries are committed.
+
+| Role | Family | Weights |
+|---|---|---|
+| Display / headings | Space Grotesk | 400 500 600 700 |
+| Body / UI text | Manrope | 400 500 600 700 800 |
+| Code / mono / data | IBM Plex Mono | 400 500 600 |
+
+CSS variable references:
+
+```css
+--font-display: "Space Grotesk", sans-serif;
+--font-body:    "Manrope", sans-serif;
+--font-mono:    "IBM Plex Mono", monospace;
+```
+
+Replace with licensed ADL brand font binaries when they become available;
+update `fonts.css` to use `@font-face` declarations pointing to local files.