claude-code-session-manager 0.55.1 → 0.56.0

package/src/main/bilkoHost.cjs

@@ -0,0 +1,305 @@
+'use strict';
+
+/**
+ * bilkoHost.cjs — Stage A (deterministic bundle prep) for the "Host on
+ * Bilko.run" tab. See session-manager-operations/architecture/
+ * bilko-host-integration.md for the full design.
+ *
+ * Model: ONE Bilko project (slug) hosts a LIST of documents — a root
+ * document (subpath '', dist/index.html — "the project itself") plus any
+ * number of sub-path documents (subpath 'special-doc/01',
+ * dist/special-doc/01/index.html → bilko.run/projects/<slug>/special-doc/01/).
+ * `documents.json` is the list; `dist/` is always rebuilt wholesale from it
+ * (rm + rewrite) so it can never drift from the list — the same "full
+ * replace" semantics Bilko's own publish_static_project already uses, which
+ * is exactly what makes local deletion reliably propagate live (see
+ * bilkoHostCore.cjs's header comment).
+ *
+ * This module owns `session-manager-operations/bilko-host/documents.json` +
+ * `dist/{**,manifest.json}` (writer id `bilko-host`, OWNERS-enforced via
+ * config.cjs's write helpers). It never talks to the bilko-host MCP itself
+ * and never writes publish-state.json — that's Stage B, run by the
+ * bilko-host-publisher Epic's own session with its own Write tool
+ * (agent-authored artifact, same as project-pages/output/*.html; not
+ * enforceable by OWNERS). Directory removal (rm -rf of dist/ before a
+ * rebuild) uses raw fs directly, same precedent as epicMint.cjs/
+ * queueStore.cjs using raw fs for their own owned namespace — this module
+ * IS the declared owner of `bilko-host`, so there is no foreign-writer risk
+ * to guard against here.
+ */
+
+const { ipcMain } = require('electron');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { gzipSync } = require('node:zlib');
+const config = require('./config.cjs');
+const {
+  validateSubpath,
+  validateDocumentSet,
+  documentDistRelPath,
+  documentUrl,
+} = require('./bilkoHostCore.cjs');
+
+const WRITER = 'bilko-host';
+const PROJECT_PAGE_LENSES = new Set(['home', 'marketing', 'feature', 'architecture']);
+
+function bilkoHostDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'bilko-host');
+}
+
+function distDir(cwd) {
+  return path.join(bilkoHostDir(cwd), 'dist');
+}
+
+function documentsPath(cwd) {
+  return path.join(bilkoHostDir(cwd), 'documents.json');
+}
+
+/** Kebab-case a project name into a slug candidate. Pure. */
+function deriveSlug(projectDirName) {
+  return String(projectDirName)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'project';
+}
+
+function gitInfo(cwd) {
+  const run = (args, fallback) => {
+    try {
+      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    } catch {
+      return fallback;
+    }
+  };
+  return {
+    gitSha: run(['rev-parse', '--short', 'HEAD'], '0000000'),
+    gitBranch: run(['rev-parse', '--abbrev-ref', 'HEAD'], 'main'),
+  };
+}
+
+async function readDocuments(cwd) {
+  const result = await config.readJson(documentsPath(cwd));
+  if (result.exists && !result.parseError && Array.isArray(result.data?.documents)) {
+    return result.data.documents;
+  }
+  return null;
+}
+
+async function writeDocuments(cwd, documents) {
+  await config.writeJson(documentsPath(cwd), { documents }, { writer: WRITER });
+}
+
+/**
+ * Reads everything the tab needs to render its status card: whether a
+ * Project Page exists to seed a root document from, the project's
+ * package.json (for the compatibility gate + default slug/version), the
+ * current document list, and any bundle/publish state already on disk.
+ */
+async function get({ cwd }) {
+  const realCwd = config.validatePath(cwd);
+
+  const marketingResult = await config.readText(
+    path.join(realCwd, 'session-manager-operations', 'project-pages', 'output', 'marketing.html'),
+  );
+  const pkgResult = await config.readJson(path.join(realCwd, 'package.json'));
+  const pkg = pkgResult.exists && !pkgResult.parseError ? pkgResult.data : null;
+
+  const documents = (await readDocuments(realCwd)) ?? [];
+
+  const bundleManifestResult = await config.readJson(path.join(distDir(realCwd), 'manifest.json'));
+  const bundleManifest = bundleManifestResult.exists && !bundleManifestResult.parseError
+    ? bundleManifestResult.data
+    : null;
+
+  const publishStateResult = await config.readJson(path.join(bilkoHostDir(realCwd), 'publish-state.json'));
+  const publishState = publishStateResult.exists && !publishStateResult.parseError
+    ? publishStateResult.data
+    : null;
+
+  const slug = bundleManifest?.slug
+    ?? deriveSlug(pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd));
+
+  return {
+    hasMarketingPage: marketingResult.exists,
+    projectName: pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd),
+    packagePrivate: pkg ? pkg.private === true : false,
+    packageHomepage: pkg && typeof pkg.homepage === 'string' ? pkg.homepage : null,
+    packageVersion: pkg && typeof pkg.version === 'string' ? pkg.version : '0.0.0',
+    defaultSlug: deriveSlug(pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd)),
+    documents: documents.map((d) => ({ ...d, url: documentUrl(slug, d.subpath) })),
+    // A rebuild is owed whenever the bundle on disk doesn't reflect the
+    // current document list — the tab uses this to gray out "up to date"
+    // vs. prompt "Prepare Bundle" again, and (post-publish) to warn that a
+    // removed document is still live until the next Publish.
+    bundleStale: bundleManifest ? bundleManifest.documentCount !== documents.length : documents.length > 0,
+    bundleManifest,
+    publishState,
+  };
+}
+
+/** Seeds documents.json with a single root document (the Marketing Project Page) if it doesn't exist yet. */
+async function ensureSeededDocuments(cwd) {
+  const existing = await readDocuments(cwd);
+  if (existing) return existing;
+  const seeded = [{
+    id: crypto.randomUUID(),
+    subpath: '',
+    title: 'Project (Marketing)',
+    source: { kind: 'project-page-lens', lens: 'marketing' },
+    addedAt: new Date().toISOString(),
+  }];
+  await writeDocuments(cwd, seeded);
+  return seeded;
+}
+
+/**
+ * Add a hosted document. `source` is either
+ * `{ kind: 'project-page-lens', lens: 'home'|'marketing'|'feature'|'architecture' }`
+ * (reuses an already-generated Project Page lens) or
+ * `{ kind: 'file', path: <repo-relative path> }` (any other local HTML —
+ * e.g. a HUMAN_LEARN page or a hand-authored explainer).
+ */
+async function addDocument({ cwd, subpath, title, source }) {
+  const realCwd = config.validatePath(cwd);
+  const subpathCheck = validateSubpath(subpath);
+  if (!subpathCheck.ok) throw new Error(subpathCheck.error);
+  if (source.kind === 'project-page-lens' && !PROJECT_PAGE_LENSES.has(source.lens)) {
+    throw new Error(`unknown Project Page lens: ${source.lens}`);
+  }
+
+  const documents = (await readDocuments(realCwd)) ?? await ensureSeededDocuments(realCwd);
+  if (subpath === '') {
+    throw new Error('the root document (subpath "") always exists — edit it instead of adding a second one');
+  }
+  if (documents.some((d) => d.subpath === subpath)) {
+    throw new Error(`a document already uses subpath "${subpath}"`);
+  }
+
+  const next = [...documents, {
+    id: crypto.randomUUID(),
+    subpath,
+    title,
+    source,
+    addedAt: new Date().toISOString(),
+  }];
+  const setCheck = validateDocumentSet(next);
+  if (!setCheck.ok) throw new Error(setCheck.error);
+
+  await writeDocuments(realCwd, next);
+  return { documents: next };
+}
+
+/**
+ * Remove a hosted document (never the root). This only updates
+ * documents.json — the file stays in `dist/` (and, if already published,
+ * live on bilko.run) until the next Prepare Bundle + Publish, which is the
+ * confirmed mechanism that actually removes it (Bilko's publish tool
+ * rm -rf's + rebuilds the whole slug directory every publish).
+ */
+async function removeDocument({ cwd, id }) {
+  const realCwd = config.validatePath(cwd);
+  const documents = (await readDocuments(realCwd)) ?? [];
+  const target = documents.find((d) => d.id === id);
+  if (!target) throw new Error(`no document with id ${id}`);
+  if (target.subpath === '') throw new Error('cannot remove the root document');
+
+  const next = documents.filter((d) => d.id !== id);
+  await writeDocuments(realCwd, next);
+  return { documents: next };
+}
+
+async function resolveDocumentHtml(cwd, doc) {
+  if (doc.source.kind === 'project-page-lens') {
+    const result = await config.readText(
+      path.join(cwd, 'session-manager-operations', 'project-pages', 'output', `${doc.source.lens}.html`),
+    );
+    if (!result.exists) {
+      throw new Error(`document "${doc.title}" points at the ${doc.source.lens} Project Page, but it hasn't been generated yet`);
+    }
+    return result.text;
+  }
+  if (doc.source.kind === 'file') {
+    const abs = config.validatePath(path.join(cwd, doc.source.path));
+    const result = await config.readText(abs);
+    if (!result.exists) throw new Error(`document "${doc.title}"'s source file is missing: ${doc.source.path}`);
+    return result.text;
+  }
+  throw new Error(`unknown document source kind: ${doc.source.kind}`);
+}
+
+/**
+ * Stage A: rebuild the ENTIRE dist/ tree from documents.json (rm + rewrite,
+ * mirroring Bilko's own full-replace publish semantics so local state can
+ * never lag the document list) + dist/manifest.json (host-contract manifest
+ * schema, one per bundle — golden.path/expect always point at the root
+ * document). Idempotent.
+ */
+async function prepareBundle({ cwd, slug }) {
+  const realCwd = config.validatePath(cwd);
+  const documents = await ensureSeededDocuments(realCwd);
+
+  const setCheck = validateDocumentSet(documents);
+  if (!setCheck.ok) throw new Error(setCheck.error);
+
+  const pkgResult = await config.readJson(path.join(realCwd, 'package.json'));
+  const pkg = pkgResult.exists && !pkgResult.parseError ? pkgResult.data : {};
+  const version = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+
+  const dist = distDir(realCwd);
+  await fsp.rm(dist, { recursive: true, force: true });
+
+  let totalGz = 0;
+  for (const doc of documents) {
+    const html = await resolveDocumentHtml(realCwd, doc);
+    const relPath = documentDistRelPath(doc.subpath);
+    await config.writeTextAtomic(path.join(dist, relPath), html, { writer: WRITER });
+    totalGz += gzipSync(Buffer.from(html, 'utf8')).length;
+  }
+
+  const { gitSha, gitBranch } = gitInfo(realCwd);
+  const goldenExpect = pkg && typeof pkg.name === 'string' ? pkg.name : slug;
+
+  const manifest = {
+    schemaVersion: 1,
+    slug,
+    version,
+    builtAt: new Date().toISOString(),
+    gitSha,
+    gitBranch,
+    hostKit: { version: '0.0.0' },
+    golden: { path: `/projects/${slug}/`, expect: goldenExpect },
+    health: {},
+    bundle: { sizeBytesGz: totalGz, fileCount: documents.length },
+    // Not part of the host-contract schema itself — this app's own staleness
+    // check (get()'s bundleStale) compares this against documents.length.
+    documentCount: documents.length,
+    documents: documents.map((d) => ({ subpath: d.subpath, title: d.title })),
+  };
+
+  await config.writeJson(path.join(dist, 'manifest.json'), manifest, { writer: WRITER });
+
+  return { distPath: dist, manifest };
+}
+
+function registerBilkoHostIpc() {
+  const { schemas: s, validated: v } = require('./ipcSchemas.cjs');
+  ipcMain.handle('bilko-host:get', v(s.bilkoHostCwd, get));
+  ipcMain.handle('bilko-host:prepare-bundle', v(s.bilkoHostPrepareBundle, prepareBundle));
+  ipcMain.handle('bilko-host:add-document', v(s.bilkoHostAddDocument, addDocument));
+  ipcMain.handle('bilko-host:remove-document', v(s.bilkoHostRemoveDocument, removeDocument));
+}
+
+module.exports = {
+  registerBilkoHostIpc,
+  get,
+  prepareBundle,
+  addDocument,
+  removeDocument,
+  deriveSlug,
+  bilkoHostDir,
+  distDir,
+};

package/src/main/bilkoHostCore.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * bilkoHostCore.cjs — pure logic for the "Host on Bilko.run" tab's
+ * multi-document bundle model. No fs/IPC here (that's bilkoHost.cjs) so
+ * this stays unit-testable without a real project directory.
+ *
+ * Model: ONE Bilko project (one registry slug, one `dist/` tree) can host
+ * MANY documents — exactly one root document (subpath `''`, becomes
+ * dist/index.html — "the project itself") plus any number of sub-path
+ * documents (subpath 'special-doc/01', becomes dist/special-doc/01/
+ * index.html → bilko.run/projects/<slug>/special-doc/01/). This mirrors how
+ * Bilko's own publish_static_project already works: it `rm -rf`s then
+ * `cp -r`s the WHOLE public/projects/<slug>/ tree on every publish, so
+ * removing a document locally and re-publishing is guaranteed to remove it
+ * live too — no separate per-document delete API needed on Bilko's side.
+ */
+
+const SUBPATH_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_SEGMENTS = 6;
+const MAX_SUBPATH_LENGTH = 200;
+
+/**
+ * Validates a document's subpath. `''` (root) is always valid. Otherwise
+ * every '/'-separated segment must be lowercase kebab-case, no '.'/'..',
+ * no leading/trailing/double slashes, bounded depth and length.
+ */
+function validateSubpath(subpath) {
+  if (typeof subpath !== 'string') return { ok: false, error: 'subpath must be a string' };
+  if (subpath === '') return { ok: true, error: null };
+  if (subpath.length > MAX_SUBPATH_LENGTH) return { ok: false, error: 'subpath is too long' };
+  if (subpath.startsWith('/') || subpath.endsWith('/')) {
+    return { ok: false, error: 'subpath must not start or end with /' };
+  }
+  const segments = subpath.split('/');
+  if (segments.length > MAX_SEGMENTS) return { ok: false, error: `subpath has more than ${MAX_SEGMENTS} segments` };
+  for (const seg of segments) {
+    if (!SUBPATH_SEGMENT.test(seg)) {
+      return { ok: false, error: `invalid subpath segment "${seg}" — use lowercase kebab-case` };
+    }
+  }
+  return { ok: true, error: null };
+}
+
+/**
+ * Validates a full document list: subpaths individually valid, exactly one
+ * root document, no duplicate subpaths. Pure — takes the array shape
+ * documents.json stores, `[{ id, subpath, ... }]`.
+ */
+function validateDocumentSet(documents) {
+  if (!Array.isArray(documents) || documents.length === 0) {
+    return { ok: false, error: 'at least one document (the root) is required' };
+  }
+  const seen = new Set();
+  let rootCount = 0;
+  for (const doc of documents) {
+    const v = validateSubpath(doc.subpath);
+    if (!v.ok) return { ok: false, error: `document "${doc.id}": ${v.error}` };
+    if (seen.has(doc.subpath)) return { ok: false, error: `duplicate subpath "${doc.subpath}"` };
+    seen.add(doc.subpath);
+    if (doc.subpath === '') rootCount += 1;
+  }
+  if (rootCount !== 1) return { ok: false, error: 'exactly one document must have subpath "" (the project root)' };
+  return { ok: true, error: null };
+}
+
+/** Where a document's rendered HTML lands inside dist/. Pure path math. */
+function documentDistRelPath(subpath) {
+  return subpath === '' ? 'index.html' : `${subpath}/index.html`;
+}
+
+/**
+ * The bilko.run URL a document resolves to once published, given the
+ * project's slug. Pure — used by the tab to render "will be live at" links
+ * before anything is actually published.
+ */
+function documentUrl(slug, subpath) {
+  return subpath === '' ? `https://bilko.run/projects/${slug}/` : `https://bilko.run/projects/${slug}/${subpath}/`;
+}
+
+module.exports = {
+  SUBPATH_SEGMENT,
+  MAX_SEGMENTS,
+  MAX_SUBPATH_LENGTH,
+  validateSubpath,
+  validateDocumentSet,
+  documentDistRelPath,
+  documentUrl,
+};

package/src/main/config.cjs

@@ -170,6 +170,14 @@ function validateWrite(realAbs) {
       if (realAbs === briefSub || realAbs.startsWith(briefSub + path.sep)) {
         return;
       }
+      // Host on Bilko.run bundle prep (bilkoHost.cjs's prepareBundle/
+      // addDocument/removeDocument): narrowly scoped to
+      // session-manager-operations/bilko-host/, this repo's existing
+      // per-project artifact-store convention.
+      const bilkoHostSub = path.join(realRoot, 'session-manager-operations', 'bilko-host');
+      if (realAbs === bilkoHostSub || realAbs.startsWith(bilkoHostSub + path.sep)) {
+        return;
+      }
     }
   }
   throw new Error(`Write outside allowed write boundaries: ${realAbs}`);

package/src/main/index.cjs

@@ -62,6 +62,7 @@ const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
 const { registerProjectBriefIpc } = require('./projectBrief.cjs');
 const { registerProjectPagesIpc } = require('./projectPages.cjs');
+const { registerBilkoHostIpc } = require('./bilkoHost.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
@@ -821,6 +822,7 @@ activeIndexMerge.registerActiveIndexMergeHandlers();
 registerMemoryAggregateIpc();
 registerProjectBriefIpc();
 registerProjectPagesIpc();
+registerBilkoHostIpc();
 ipcMain.handle('promptSessionTranscript:append', validated(schemas.promptSessionTranscriptAppend, async ({ cwd, epicId, role, text, at, eventId }) => {
   const ok = await promptSessionTranscript.appendTurn(cwd, epicId, { role, text, at, eventId });
   return { ok };

package/src/main/ipcSchemas.cjs

@@ -486,6 +486,31 @@ const projectBriefCwd = z.object({
 const projectPagesCwd = z.object({
   cwd: z.string().min(1).max(4096),
 }).strict();
+
+// ──────────────────────────────────────────── Host on Bilko.run
+// Same validation split: real path validation is config.cjs's validatePath
+// at first fs access in bilkoHost.cjs — these schemas only bound wire shape.
+const bilkoHostCwd = z.object({
+  cwd: z.string().min(1).max(4096),
+}).strict();
+const bilkoHostPrepareBundle = z.object({
+  cwd: z.string().min(1).max(4096),
+  slug: z.string().min(1).max(64).regex(/^[a-z0-9-]+$/, 'slug must be lowercase kebab-case'),
+}).strict();
+const BILKO_HOST_DOCUMENT_SOURCE = z.union([
+  z.object({ kind: z.literal('project-page-lens'), lens: z.enum(['home', 'marketing', 'feature', 'architecture']) }).strict(),
+  z.object({ kind: z.literal('file'), path: z.string().min(1).max(4096) }).strict(),
+]);
+const bilkoHostAddDocument = z.object({
+  cwd: z.string().min(1).max(4096),
+  subpath: z.string().min(1).max(200),
+  title: z.string().min(1).max(200),
+  source: BILKO_HOST_DOCUMENT_SOURCE,
+}).strict();
+const bilkoHostRemoveDocument = z.object({
+  cwd: z.string().min(1).max(4096),
+  id: z.string().min(1).max(200),
+}).strict();
 const projectBriefSetPin = z.object({
   cwd: z.string().min(1).max(4096),
   block: PROJECT_BRIEF_BLOCK,
@@ -937,6 +962,10 @@ module.exports = {
     memoryStale,
     projectBriefCwd,
     projectPagesCwd,
+    bilkoHostCwd,
+    bilkoHostPrepareBundle,
+    bilkoHostAddDocument,
+    bilkoHostRemoveDocument,
     projectBriefSetPin,
     projectBriefUpdate,
     promptSessionTranscriptAppend,

package/src/main/lib/opsOwnership.cjs

@@ -54,6 +54,11 @@ const OWNERS = Object.freeze({
   'browser': 'browser',
   // Structured per-tab error log lines (JSONL), tagged for tracing/analysis.
   'logs': 'logs',
+  // Host on Bilko.run tab's deterministic bundle prep (dist/index.html +
+  // dist/manifest.json only — publish-state.json and anything the
+  // bilko-host-publisher Epic authors beyond dist/ is agent-Write-tool
+  // output, same unenforceable-by-construction class as project-pages/output.
+  'bilko-host': 'bilko-host',
 });
 
 /**

package/src/main/projectPages.cjs

@@ -21,7 +21,7 @@ function outputDir(cwd) {
   return path.join(cwd, 'session-manager-operations', 'project-pages', 'output');
 }
 
-const LENSES = ['marketing', 'feature', 'architecture'];
+const LENSES = ['home', 'marketing', 'feature', 'architecture'];
 
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
@@ -38,7 +38,7 @@ async function get({ cwd }) {
     return { output: null };
   }
 
-  const [marketing, feature, architecture] = htmlResults;
+  const [home, marketing, feature, architecture] = htmlResults;
   const generatedAt = typeof manifestResult.data.generatedAt === 'string' ? manifestResult.data.generatedAt : null;
   if (!generatedAt) {
     return { output: null };
@@ -46,6 +46,7 @@ async function get({ cwd }) {
 
   return {
     output: {
+      home: home.text,
       marketing: marketing.text,
       feature: feature.text,
       architecture: architecture.text,

package/src/preload/api.d.ts

@@ -987,6 +987,7 @@ export type ProjectBriefUpdateResult =
 
 // ────────────────────────────────────────────── Project Pages (PRD 929-932)
 export interface ProjectPagesOutput {
+  home: string;
   marketing: string;
   feature: string;
   architecture: string;
@@ -998,6 +999,76 @@ export interface ProjectPagesGetResult {
   output: ProjectPagesOutput | null;
 }
 
+// ────────────────────────────────────────────── Host on Bilko.run
+export interface BilkoHostBundleManifest {
+  schemaVersion: 1;
+  slug: string;
+  version: string;
+  builtAt: string;
+  gitSha: string;
+  gitBranch: string;
+  hostKit: { version: string };
+  golden: { path: string; expect: string };
+  health: Record<string, unknown>;
+  bundle: { sizeBytesGz: number; fileCount: number };
+  /** Not part of the host-contract schema itself — this app's own staleness bookkeeping (see BilkoHostGetResult.bundleStale). */
+  documentCount: number;
+  documents: Array<{ subpath: string; title: string }>;
+}
+
+export type BilkoHostPublishStatus =
+  | 'not-published'
+  | 'bundle-ready'
+  | 'publishing'
+  | 'published'
+  | 'publish-failed';
+
+export interface BilkoHostPublishState {
+  status: BilkoHostPublishStatus;
+  slug: string;
+  url?: string;
+  lastAttemptAt?: string;
+  lastError?: string;
+}
+
+export type BilkoHostDocumentSource =
+  | { kind: 'project-page-lens'; lens: 'home' | 'marketing' | 'feature' | 'architecture' }
+  | { kind: 'file'; path: string };
+
+export interface BilkoHostDocument {
+  id: string;
+  /** '' for the root document (dist/index.html); otherwise a '/'-joined lowercase-kebab path, e.g. 'special-doc/01'. */
+  subpath: string;
+  title: string;
+  source: BilkoHostDocumentSource;
+  addedAt: string;
+  /** Where this document resolves once published, given the project's current/derived slug. */
+  url: string;
+}
+
+export interface BilkoHostGetResult {
+  hasMarketingPage: boolean;
+  projectName: string;
+  packagePrivate: boolean;
+  packageHomepage: string | null;
+  packageVersion: string;
+  defaultSlug: string;
+  documents: BilkoHostDocument[];
+  /** True when the on-disk dist/ bundle doesn't reflect the current document list — Prepare Bundle (then Publish) is owed. */
+  bundleStale: boolean;
+  bundleManifest: BilkoHostBundleManifest | null;
+  publishState: BilkoHostPublishState | null;
+}
+
+export interface BilkoHostPrepareBundleResult {
+  distPath: string;
+  manifest: BilkoHostBundleManifest;
+}
+
+export interface BilkoHostDocumentListResult {
+  documents: Array<Omit<BilkoHostDocument, 'url'>>;
+}
+
 // ────────────────────────────────────────────── Per-subagent memory
 // Stored at ~/.claude/session-manager/agent-memory/<agentId>.json. Keyed by
 // agent name (the .md filename in ~/.claude/agents/), not by workspace cwd.
@@ -1148,7 +1219,7 @@ export interface ChatCreatePrdPayload {
   /** Originating tab id — used at job completion to route a status prompt back into the tab. */
   sourceTabId?: string;
   /** User-selected Feature/Bug tag (PRD 774) carried from the originating PromptTicket. */
-  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder';
+  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
 }
 
 export type ChatCreatePrdResult =
@@ -1568,6 +1639,16 @@ export interface SessionManagerAPI {
     /** Read output/*.html + manifest.json (or `{output: null}` if none exist yet). Never fires an LLM call. */
     get: (cwd: string) => Promise<ProjectPagesGetResult>;
   };
+  bilkoHost: {
+    /** Read compatibility-gate inputs + any existing bundle/publish state. Never fires an LLM call. */
+    get: (cwd: string) => Promise<BilkoHostGetResult>;
+    /** Stage A: rebuild the whole dist/ tree + dist/manifest.json from the current document list. Pure, no cost, idempotent. */
+    prepareBundle: (cwd: string, slug: string) => Promise<BilkoHostPrepareBundleResult>;
+    /** Add a hosted sub-path document (never the root, which always exists). Does not touch dist/ — Prepare Bundle picks it up. */
+    addDocument: (cwd: string, subpath: string, title: string, source: BilkoHostDocumentSource) => Promise<BilkoHostDocumentListResult>;
+    /** Remove a hosted document (never the root). Only updates documents.json — the file stays live until the next Prepare Bundle + Publish. */
+    removeDocument: (cwd: string, id: string) => Promise<BilkoHostDocumentListResult>;
+  };
   promptSessionTranscript: {
     /** Append one full-text turn to an Epic's durable JSONL transcript. Best-effort — resolves `{ok:false}` rather than throwing on failure. */
     append: (

package/src/preload/index.cjs

@@ -343,6 +343,13 @@ contextBridge.exposeInMainWorld('api', {
   projectPages: {
     get: (cwd) => ipcRenderer.invoke('project-pages:get', { cwd }),
   },
+  bilkoHost: {
+    get: (cwd) => ipcRenderer.invoke('bilko-host:get', { cwd }),
+    prepareBundle: (cwd, slug) => ipcRenderer.invoke('bilko-host:prepare-bundle', { cwd, slug }),
+    addDocument: (cwd, subpath, title, source) =>
+      ipcRenderer.invoke('bilko-host:add-document', { cwd, subpath, title, source }),
+    removeDocument: (cwd, id) => ipcRenderer.invoke('bilko-host:remove-document', { cwd, id }),
+  },
   promptSessionTranscript: {
     append: (cwd, epicId, turn) =>
       ipcRenderer.invoke('promptSessionTranscript:append', { cwd, epicId, ...turn }),