website-build-skill 0.1.0

package/skills/website-build-skill/templates/install-choice.txt

@@ -0,0 +1,28 @@
+How do you want to work?
+
+  1  Teach my AI          One AI learns the whole thing and does every job itself.
+                          Works with any AI: Claude, ChatGPT, Grok, Cursor, Copilot.
+                          Nothing else to install.
+
+  2  Give me the team     Seven specialist agents, one per job, starting with a researcher that gets them all current.
+                          Needs Claude Code, Codex, Hermes, Antigravity, or Grok Bot.
+                          One command installs their files; you open each session yourself.
+
+Not sure? Pick 1. Moving to 2 later costs you nothing you have already done.
+
+Where should the work be saved?
+
+  1  Obsidian vault       Give an existing folder inside your vault. The library is
+                          plain Markdown, so it opens and links natively.
+
+  2  A folder on this computer
+                          Give an existing directory. The default is the
+                          website project folder.
+
+  3  Notion               Working copy still lives in a folder on this computer,
+                          because every gate reads its own files back by path.
+                          Notion receives an export of the finished library.
+
+  4  Somewhere else       Type an existing local destination yourself.
+
+Whatever you pick becomes the workspace root. Everything below is written inside it.

package/skills/website-build-skill/templates/site-operations.md

@@ -0,0 +1,71 @@
+# Site operations
+
+Date rule: [ASK DATE and evidence provenance](../playbooks/research-and-memory.md#ask-date-rule).
+This is a blank artifact contract. Fill it from actual inputs and evidence at runtime.
+Unresolved required fields keep the relevant gate BLOCKED; never prefill a PASS.
+
+## What and why
+
+Record audience, primary action, public destination, implementation source and current artifact.
+Name the operational owner by approved role or contact mechanism, never by invented identity.
+
+## Trigger
+
+State what starts content updates, scheduled publication, builds and release promotion.
+Name the actual scheduler or manual owner. If nothing is scheduled, say manual.
+A date in a template does not create a rebuild trigger.
+
+## Invocation chain
+
+Write the exact sequence from content edit through validation, image generation, build,
+preview, checks, promotion and live verification. Include working directories and commands
+as project-relative paths. Record the operator and failure stop at each step.
+Do not require a second document to reconstruct the procedure.
+
+## Dependencies
+
+List verified runtime/tool versions, dependency lock, host plan, integrations and access roles.
+Name credential storage/injection mechanisms and environment variable names only.
+Do not include secret values, authenticated links or personal machine paths.
+
+## Reads
+
+List content records, assets, brand tokens, approved discovery inputs, configuration,
+external resources, and authority needed to read each.
+
+## Writes
+
+List generated output, deployment target, logs, analytics/event side effects,
+and any runtime persistence with owners and retention constraints.
+Keep private research, raw brand sources, scratch artifacts and credentials out of uploads.
+
+## The closed loop
+
+Name what watches the site, including nothing when no watcher exists.
+For each watcher record check, cadence, expected signal, recipient and response procedure.
+State how missed instrumentation or a broken watcher becomes visible.
+If manual only, name the responsible role and the concrete manual verification trigger.
+
+## Failure modes
+
+| Symptom | Diagnostic command/action | Expected evidence | Recovery | Responsible role |
+| --- | --- | --- | --- | --- |
+
+Cover failed builds, bad routes/assets, CSP breakage, form/integration failure,
+stale scheduled content, invalid discovery data, unavailable credentials and failed deploys.
+Record rollback identity, retention limits and safe recovery for an initial release.
+
+## Run-and-verify by hand
+
+Provide exact content editing, clean build, tests, preview, promotion and rollback commands.
+For each command include environment requirements, observed success evidence and failure response.
+Include live HTTPS, route, error, asset, primary journey, header and metadata checks.
+Include verification after rollback, not only the restoration command.
+Mark every untested procedure UNVERIFIED with the exact settling test.
+
+## Source of truth
+
+Identify maintained source, content owner, approved research/brand/design revisions,
+current deployed artifact, build recipe, configuration authority and release receipt.
+Explain which generated files must not be edited and how future changes reopen affected gates.
+Keep this document updated with the deployed artifact and actual watcher state.

package/skills/website-build-skill/templates/status.md

@@ -0,0 +1,47 @@
+# Website stage status
+
+Date rule: [ASK DATE and evidence provenance](../playbooks/research-and-memory.md#ask-date-rule).
+This is a blank artifact contract. Fill it from actual inputs and evidence at runtime.
+Unresolved required fields keep the relevant gate BLOCKED; never prefill a PASS.
+
+## Current state
+
+- Engagement: reference the stable request and scope.md ASK DATE provenance.
+- Mode: recorded SOLO or TEAM, actual workers and family evidence.
+- Stage: name the active stage and accountable role.
+- Revision: record current brief, library, brand, mockup, source and candidate identities.
+- Next action: name one concrete action, owner, prerequisite and expected evidence.
+
+## Gate acceptance
+
+| Stage | Producer receipt | Artifact revision | Required checks | Status | Accepted evidence | Next owner |
+| --- | --- | --- | --- | --- | --- | --- |
+
+Coordinator alone writes acceptance after opening the producer's artifacts.
+Use PASS, FAIL, BLOCKED or reasoned NOT APPLICABLE, never an unsupported complete label.
+Research precedes every other role; three visuals and a named selection precede site code.
+Internal review leaves independent gate NOT MET and ship BLOCKED.
+Keep pre-promotion and live-release verification separate.
+
+## User decisions
+
+| Decision | Exact scope | Source evidence | Approved revision | Affected stages |
+| --- | --- | --- | --- | --- |
+
+Record existing instructions and decisions without requesting them again.
+Silence is not a mockup selection or release authorization.
+
+## Blockers and invalidation
+
+| Check or claim | Failure/limit | Dependent work paused | Owner | Settling action | Recheck evidence |
+| --- | --- | --- | --- | --- | --- |
+
+Invalidate affected receipts after changed scope, sources, artifact or expiry.
+Preserve the previous result as history rather than silently replacing it.
+
+## Release and follow-through
+
+Record exact target/authority, reviewed and final artifact identities, independent family
+proof, ROUND 1 disposition, preview/live receipt, rollback, operations document and watcher.
+Keep missing field data, cache observations and receiving-property access UNVERIFIED with owners.
+Record pending memory separately from saved/read-back project artifacts.

package/skills/website-build-skill/templates/tokens.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": 1,
+  "description": "Synthetic starting values for mapping primitive and semantic roles, not an approved brand.",
+  "dateRule": "playbooks/research-and-memory.md#ask-date-rule",
+  "approvalStatus": "UNAPPROVED",
+  "provenance": {
+    "synthetic-example": {
+      "kind": "invented",
+      "source": "This contract only",
+      "rightsStatus": "No external asset supplied",
+      "approvalEvidence": null
+    }
+  },
+  "primitive": {
+    "paper": {
+      "value": "#FAF7EF",
+      "sourceId": "synthetic-example"
+    },
+    "ink": {
+      "value": "#202823",
+      "sourceId": "synthetic-example"
+    },
+    "leaf": {
+      "value": "#276443",
+      "sourceId": "synthetic-example"
+    },
+    "stone": {
+      "value": "#616A64",
+      "sourceId": "synthetic-example"
+    }
+  },
+  "semantic": {
+    "canvas": "paper",
+    "surface": "paper",
+    "text": "ink",
+    "mutedText": "stone",
+    "accent": "leaf",
+    "actionBackground": "leaf",
+    "actionText": "paper",
+    "border": "stone",
+    "focus": "ink",
+    "error": null,
+    "success": "leaf"
+  },
+  "typography": {
+    "body": {
+      "family": "system-ui, sans-serif",
+      "weight": 400
+    },
+    "heading": {
+      "family": "system-ui, sans-serif",
+      "weight": 700
+    },
+    "externalFontRights": "No font files supplied"
+  },
+  "spacing": {
+    "unit": "rem",
+    "small": 0.5,
+    "medium": 1,
+    "large": 2
+  },
+  "motion": {
+    "reducedMotion": "Remove nonessential movement; retain state information"
+  },
+  "contrast": {
+    "status": "UNVERIFIED",
+    "method": null,
+    "ratios": [],
+    "requiredCheck": "checklists/accessibility.md AX01"
+  },
+  "usage": "Assign missing roles and compute actual rendered contrast before approval. Do not claim the synthetic values are accessible or selected."
+}

package/src/agents.mjs

@@ -0,0 +1,7 @@
+// Planned native generation. Unknown host schemas must fail closed.
+// Required future implementation: full canonical bodies, reference rebasing,
+// observed tool mapping, read-only Reviewer, research-first setup acknowledgements,
+// Hermes declarative/session branch evidence and separate activation receipts.
+export function generateAgents(_request) {
+  throw Error('UNAVAILABLE: native agent generation is planned; use the full team bundle.');
+}

package/src/bundle.mjs

@@ -0,0 +1,106 @@
+import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
+import { resolve, relative, dirname, sep, posix } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const CORE = 'skills/website-build-skill';
+export const ARCHIVE = 'archive/graphics-design-original.md';
+export const ARCHIVE_SHA = 'd985b6fcaf5c0de9c6d60f2511bb9fa5728ad0d2d543a64a673962647ea5388a';
+export const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+// Resolve only existing, regular, repository-owned inputs. Never follow a symlink.
+export function owned(root, name, mustExist = true) {
+  if (typeof name !== 'string' || !name || name.includes('\\') || name.startsWith('/') || /^[A-Za-z]:/.test(name)) throw Error('invalid owned path');
+  const base = resolve(root), full = resolve(base, name);
+  if (full !== base && !full.startsWith(base + sep)) throw Error('path escapes repository');
+  let part = base;
+  if (lstatSync(base).isSymbolicLink()) throw Error('symlink root');
+  for (const segment of relative(base, full).split(sep).filter(Boolean)) {
+    part = resolve(part, segment);
+    // existsSync follows the link, so it is FALSE for a dangling symlink and the symlink
+    // check below was skipped. An ordinary write then follows that link outside the
+    // repository. lstat never follows, so it sees the link whether or not the target exists.
+    let entry = null;
+    try { entry = lstatSync(part); } catch { entry = null; }
+    if (entry) {
+      if (entry.isSymbolicLink()) throw Error('symlink path');
+    } else if (mustExist) throw Error(`missing path: ${name}`);
+  }
+  return full;
+}
+
+export function files(root, directory = '') {
+  const out = [];
+  for (const item of readdirSync(owned(root, directory || '.'), { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name, 'en'))) {
+    if (['.git', 'node_modules', '.test-work', '.build-local'].includes(item.name)) continue;
+    // Local, gitignored working files are not part of the published tree. Reviewing them
+    // would fail the gate on notes that never ship.
+    if (/^AUDIT_BRIEF.*\.md$/.test(item.name) || /\.(plan|brief)\.md$/.test(item.name) || item.name === 'notes-local') continue;
+    const name = directory ? `${directory}/${item.name}` : item.name;
+    if (item.isSymbolicLink()) throw Error(`symlink in public tree: ${name}`);
+    if (item.isDirectory()) out.push(...files(root, name));
+    else if (item.isFile()) out.push(name);
+  }
+  return out;
+}
+
+export const read = (root, name) => readFileSync(owned(root, name), 'utf8');
+export const manifest = root => JSON.parse(read(root, `${CORE}/manifest.json`));
+
+// Rebase rendered links; bare canonical filenames retain an explicit source-base label.
+export function rebase(text, source, target) {
+  const rewrite = url => {
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url)) return url;
+    const [file, fragment] = url.split('#');
+    const destination = file ? posix.normalize(posix.join(posix.dirname(source), file)) : source;
+    return posix.relative(posix.dirname(target), destination) + (fragment === undefined ? '' : '#' + fragment);
+  };
+  let fenced = false;
+  return text.split('\n').map(line => {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) { fenced = !fenced; return line; }
+    if (fenced) return line;
+    return line.replace(/(!?\[[^\]\n]*\]\()([^\s)]+)([^)]*\))/g, (_, a, b, c) => a + rewrite(b) + c)
+      .replace(/^(\s*\[[^\]]+\]:\s*)(\S+)/, (_, a, b) => a + rewrite(b))
+      .replace(/((?:href|src)=["'])([^"']+)(["'])/g, (_, a, b, c) => a + rewrite(b) + c);
+  }).join('\n');
+}
+
+export function generated(root) {
+  const m = manifest(root), output = {};
+  const byPath = new Map(m.assets.map(a => [a.path, a]));
+  for (const [name, members] of Object.entries(m.bundles)) {
+    if (!/^(method|prompts|playbooks|checklists|team)$/.test(name)) throw Error('unknown bundle');
+    const target = `docs/bundles/${name}.md`;
+    let text = `# Website build: ${name}\n\nGenerated from the canonical manifest. Do not edit this file.\n\n`;
+    text += 'Bare skill paths in the included instructions resolve from the canonical skill directory.\n';
+    text += 'For uploads, locate the named source section in these bundles; request an attachment when absent.\n';
+    text += 'Project paths resolve only in the authorized website workspace. Native loading is UNVERIFIED.\n\n## Contents\n\n';
+    for (const member of members) {
+      const asset = byPath.get(member);
+      if (!asset?.active || member === ARCHIVE) throw Error('inactive asset requested in active bundle');
+      text += `- [${member}](../../${CORE}/${member})\n`;
+    }
+    for (const member of members) {
+      const source = `${CORE}/${member}`;
+      text += `\n<!-- BEGIN SOURCE: ${member} -->\n\n## Source: ${member}\n\n`;
+      const body = read(root, source);
+      text += member.endsWith('.md') ? rebase(body, source, target) : `\n\`\`\`text\n${body.trimEnd()}\n\`\`\`\n`;
+      text += `\n<!-- END SOURCE: ${member} -->\n`;
+    }
+    if (name === 'team') {
+      const source = 'adapters/grok.md';
+      const manual = read(root, source).split('## Manual fallback\n')[1];
+      if (!manual) throw Error('missing manual fallback');
+      text += '\n' + rebase('## Manual fallback\n' + manual, source, target);
+      text += '\n## Artifact ownership roster\n\n```yaml\n' + read(root, 'adapters/team.yaml').trimEnd() + '\n```\n';
+    }
+    output[target] = text.trimEnd() + '\n';
+  }
+  let index = '# website-build-skill\n\n> Research-first website instructions, role boundaries and evidence gates.\n\n';
+  index += 'Generated from skills/website-build-skill/manifest.json. Published at https://github.com/aunysillyme/website-build-skill. Host loading is UNVERIFIED.\n\n## Active sources\n\n';
+  for (const asset of m.assets.filter(a => a.active)) index += `- [${asset.path}](${CORE}/${asset.path}): ${asset.kind}\n`;
+  index += '\n## Bundles\n\n';
+  for (const name of Object.keys(m.bundles)) index += `- [${name}](docs/bundles/${name}.md): generated upload packet\n`;
+  index += `\n## Inactive provenance\n\n- [Graphics original](${CORE}/${ARCHIVE}): archive only; never execute\n`;
+  output['llms.txt'] = index;
+  return output;
+}

package/src/catalog.mjs

@@ -0,0 +1,12 @@
+// Candidate destinations, not a verified host support registry.
+export const targets = Object.freeze({
+  'claude-code': '.claude/skills/website-build-skill',
+  codex: '.agents/skills/website-build-skill',
+  hermes: '.agents/skills/website-build-skill',
+  antigravity: '.website-build-skill',
+  grok: '.grok/skills/website-build-skill',
+  agents: '.website-build-skill',
+  portable: '.website-build-skill',
+  chatgpt: 'website-build-skill-upload',
+});
+export const status = 'UNVERIFIED: host activation; file installer implemented';

package/src/choice.mjs

@@ -0,0 +1,6 @@
+import { CORE, read } from './bundle.mjs';
+
+// Content accessor only. Interactive installation is planned and unavailable.
+export function installQuestion(root) {
+  return read(root, `${CORE}/templates/install-choice.txt`);
+}

package/src/cli.mjs

@@ -0,0 +1,96 @@
+import { createInterface } from 'node:readline';
+import { install, packageInfo, choiceText } from './install.mjs';
+import { targets } from './catalog.mjs';
+import { checkLibrary } from './library-check.mjs';
+
+const help = `website-build-skill ${packageInfo.version}
+check-library <site-work-dir> (read-only receipt validation)
+--solo | --team  --target ${Object.keys(targets).join('|')}
+--dir <path>  --scope project|user  --output-dir <path>
+--yes  --dry-run  --receipt <path>  --uninstall  --help  --version
+--bundle-dir <path> (Hermes TEAM only)
+Headless installs require explicit mode, target and --dir.
+Activation remains UNVERIFIED.`;
+
+export function parseArgs(args) {
+  const request = {};
+  const values = { '--target': 'target', '--dir': 'dir', '--scope': 'scope', '--output-dir': 'outputDir', '--receipt': 'receipt', '--bundle-dir': 'bundleDir' };
+  const switches = { '--yes': 'yes', '--dry-run': 'dryRun', '--uninstall': 'uninstall', '--help': 'help', '--version': 'version' };
+  const seen = new Set();
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i];
+    if (seen.has(flag)) throw Error(`Duplicate flag: ${flag}`);
+    seen.add(flag);
+    if (flag === '--solo' || flag === '--team') {
+      if (request.mode) throw Error('--solo and --team are mutually exclusive');
+      request.mode = flag.slice(2);
+    } else if (Object.hasOwn(values, flag)) {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw Error(`Missing value for ${flag}`);
+      request[values[flag]] = value;
+    } else if (Object.hasOwn(switches, flag)) request[switches[flag]] = true;
+    else throw Error(`Unknown flag: ${flag}`);
+  }
+  if (request.target !== undefined && !Object.hasOwn(targets, request.target)) throw Error('Unknown target');
+  if (request.scope !== undefined && !['project', 'user'].includes(request.scope)) throw Error('Invalid scope');
+  if (request.bundleDir !== undefined && (request.mode !== 'team' || request.target !== 'hermes')) throw Error('--bundle-dir requires --team --target hermes');
+  return request;
+}
+
+export async function main(args = process.argv.slice(2), { input = process.stdin, output = process.stdout } = {}) {
+  let request;
+  try {
+    if (args[0] === 'check-library') {
+      if (args.length !== 2 || !args[1] || args[1].startsWith('--')) throw Error('Usage: website-build-skill check-library <site-work-dir>');
+      return checkLibrary(args[1]);
+    }
+    request = parseArgs(args);
+    if (request.help) return { code: 0, message: help };
+    if (request.version) return { code: 0, message: packageInfo.version };
+    if (request.uninstall) {
+      if (!request.receipt && (!request.target || !request.dir)) throw Error('Uninstall requires --receipt or --target and --dir');
+      return install(request);
+    }
+    if (request.yes && (!request.mode || !request.target || !request.dir)) throw Error('--yes requires mode, target and --dir; it never prompts');
+    if (!request.mode || !request.target || (!request.yes && !request.outputDir)) {
+      const reader = createInterface({ input, crlfDelay: Infinity });
+      const answers = reader[Symbol.asyncIterator]();
+      const ask = async text => {
+        output.write(text);
+        const answer = await answers.next();
+        if (answer.done) throw Error('Invalid input: stdin ended before an answer (EOF)');
+        // Paths and export destinations can be case-sensitive. Normalize choices only.
+        return answer.value.trim();
+      };
+      try {
+        if (!request.mode) {
+          const answer = (await ask(choiceText() + '\nWork mode (1 or 2):\n')).toLowerCase();
+          request.mode = ({ '1': 'solo', solo: 'solo', '2': 'team', team: 'team' })[answer];
+          if (!request.mode) throw Error('Invalid mode answer');
+        }
+        if (!request.target) {
+          request.target = (await ask(`Target (${Object.keys(targets).join(', ')}):\n`)).toLowerCase();
+          if (!Object.hasOwn(targets, request.target)) throw Error('Invalid target answer');
+        }
+        if (!request.yes && !request.outputDir) {
+          const answer = await ask('Save location: 1 Obsidian, 2 local folder, 3 Notion export, 4 another local destination:\n');
+          const kind = ({ '1': 'obsidian', '2': 'folder', '3': 'notion', '4': 'other' })[answer];
+          if (!kind) throw Error('Invalid save-location answer');
+          const label = kind === 'obsidian' ? 'Existing folder inside your Obsidian vault'
+            : kind === 'notion' ? 'Existing local working directory (authoritative copy)'
+            : 'Existing output directory';
+          const path = await ask(`${label}${kind === 'folder' ? ' (Enter uses the website project folder)' : ''}:\n`);
+          if (!path && kind !== 'folder') throw Error('An existing output directory is required');
+          request.outputDir = path || request.dir || process.cwd();
+          request.outputStorage = { kind };
+          if (kind === 'notion') {
+            const exportTarget = await ask('Notion export destination (page URL or name; no upload is performed):\n');
+            if (!exportTarget) throw Error('Notion export destination is required');
+            request.outputStorage.exportTarget = exportTarget;
+          }
+        }
+      } finally { reader.close(); }
+    }
+    return install(request);
+  } catch (error) { return { code: 2, message: error.message }; }
+}