@tiinex/app 0.1.1

package/src/workspaces/workspace.auditView.js

@@ -0,0 +1,153 @@
+import { auditPortableRecord } from '@tiinex/core/tooling/portable/audit/audit.capability.js';
+import { buildPortableLineageIntegrityRepairProjection } from '@tiinex/core/tooling/portable/lineage/lineage.integrity.projection.js';
+import { resolveAuditLineage } from '../audit/lineage/auditLineage.resolve.js';
+import { schemaReadPresentation } from '@tiinex/core/schemas/companion.js';
+import { schemaIdForRecord } from '@tiinex/core/schemas/schema.identity.js';
+
+export const WORKSPACE_AUDIT_VIEW_SCHEMA_ID = 'tiinex.workspace.loadedAuditView.v1';
+
+export function buildWorkspaceAuditView(workspace = {}, input = {}) {
+  const records = Array.isArray(input.records) ? input.records : (Array.isArray(workspace.records) ? workspace.records : []);
+  const query = String(input.query || '').trim().toLowerCase();
+  const lineage = resolveAuditLineage(records);
+  const repair = buildPortableLineageIntegrityRepairProjection({ records });
+  const items = records.map((record) => auditRecord(record));
+  const visibleItems = query ? items.filter((item) => auditItemMatchesQuery(item, query)) : items;
+  const visibleIds = new Set(visibleItems.map((item) => item.id));
+  const visibleLineageFindings = (lineage.findings || []).filter((finding) => !query || !finding.nodeId || visibleIds.has(finding.nodeId));
+  const counts = summarizeAuditItems(items, lineage.findings || []);
+  const visibleCounts = summarizeAuditItems(visibleItems, visibleLineageFindings);
+
+  return {
+    schema: WORKSPACE_AUDIT_VIEW_SCHEMA_ID,
+    workspaceId: workspace.id || '',
+    title: `Audit · ${workspace.title || workspace.name || 'workspace'}`,
+    mode: 'loaded-only',
+    boundary: 'Loaded material only. Audit validates Tiinex leaf candidates, keeps plain Markdown as supporting material, and reports missing lineage targets without network guesses.',
+    query,
+    items: visibleItems,
+    repair,
+    lineage: {
+      schema: lineage.schema,
+      edges: lineage.edges || [],
+      findings: visibleLineageFindings,
+      stats: lineage.stats || {}
+    },
+    counts,
+    visibleCounts,
+    empty: !visibleItems.length
+  };
+}
+
+function auditRecord(record = {}) {
+  const markdown = typeof record.markdown === 'string' ? record.markdown : '';
+  const result = auditPortableRecord(record);
+  const read = schemaReadPresentation(record, { compact: true, maxSections: 1 });
+  return {
+    id: result.id || record.id || record.path || record.title || '',
+    title: record.title || result.title || 'Untitled artifact',
+    path: record.path || '',
+    sourceLabel: record.source?.label || '',
+    sourceBacked: Boolean(record.source?.adapterId && record.source.adapterId !== 'local'),
+    status: result.status,
+    schemaId: result.schemaId || schemaIdForRecord(record),
+    moduleId: result.resolution?.moduleId || '',
+    fallbackUsed: Boolean(result.resolution?.fallbackUsed || read.fallbackUsed),
+    readState: read.readState || (result.resolution?.fallbackUsed ? 'root-fallback' : 'schema-owned'),
+    schemaCoverage: read.schemaCoverage || 'missing-schema',
+    bodyAvailability: result.materialAvailability?.status === 'pending-unavailable' ? 'unavailable-body' : (read.bodyAvailability || (markdown ? 'available' : 'unavailable-body')),
+    validation: result.validation || null,
+    validationState: result.validation?.state || 'validation-unknown',
+    validationCoverage: result.validation?.coverage || 'unknown',
+    childValidator: result.validation?.childValidator || 'unknown',
+    rootValidator: result.validation?.rootValidator || 'unknown',
+    integrityMethodVersions: result.validation?.integrityMethodVersions || [],
+    exactCompanion: Boolean(read.exactCompanion),
+    summary: result.summary || {},
+    findings: result.findings || [],
+    markdownAvailable: Boolean(markdown),
+    materialAvailability: result.materialAvailability?.status || (markdown ? 'available' : 'unknown'),
+    capabilityBoundary: result.capabilityBoundary || null,
+    record
+  };
+}
+
+function summarizeAuditItems(items = [], lineageFindings = []) {
+  const counts = {
+    records: items.length,
+    readable: 0,
+    degraded: 0,
+    invalid: 0,
+    pending: 0,
+    unavailable: 0,
+    supporting: 0,
+    fallbackUsed: 0,
+    schemaOwned: 0,
+    rootReadable: 0,
+    rootFallback: 0,
+    unknownSchema: 0,
+    unavailableBody: 0,
+    validationComplete: 0,
+    validationPartial: 0,
+    validationUnavailable: 0,
+    validationNotApplicable: 0,
+    childValidatorUnavailable: 0,
+    integrityV2: 0,
+    partialLineage: countPartialLineageNodes(lineageFindings),
+    errors: 0,
+    warnings: 0,
+    infos: 0,
+    lineageFindings: lineageFindings.length,
+    missingLineage: lineageFindings.filter((finding) => finding.code === 'lineage.parent.missing').length
+  };
+  for (const item of items) {
+    if (item.status === 'readable') counts.readable += 1;
+    else if (item.status === 'degraded') counts.degraded += 1;
+    else if (item.status === 'pending-unavailable') {
+      counts.pending += 1;
+      counts.unavailable += 1;
+    } else if (item.status === 'supporting-material') counts.supporting += 1;
+    else counts.invalid += 1;
+    if (item.fallbackUsed) counts.fallbackUsed += 1;
+    if (item.readState === 'schema-owned') counts.schemaOwned += 1;
+    if (item.readState === 'root-readable') counts.rootReadable += 1;
+    if (item.readState === 'root-fallback') counts.rootFallback += 1;
+    if (item.schemaCoverage === 'unknown-schema') counts.unknownSchema += 1;
+    if (item.bodyAvailability === 'unavailable-body') counts.unavailableBody += 1;
+    if (item.validationState === 'exact-schema-validated' || item.validationState === 'root-validated') counts.validationComplete += 1;
+    else if (item.validationState === 'root-only-child-validator-unavailable' || item.validationState === 'validation-unknown') counts.validationPartial += 1;
+    else if (item.validationState === 'not-run-body-unavailable') counts.validationUnavailable += 1;
+    else if (item.validationState === 'not-applicable-supporting') counts.validationNotApplicable += 1;
+    if (item.childValidator === 'unavailable') counts.childValidatorUnavailable += 1;
+    if ((item.integrityMethodVersions || []).includes('v2')) counts.integrityV2 += 1;
+    counts.errors += Number(item.summary?.error || 0);
+    counts.warnings += Number(item.summary?.warning || 0);
+    counts.infos += Number(item.summary?.info || 0);
+  }
+  return counts;
+}
+
+function countPartialLineageNodes(lineageFindings = []) {
+  const ids = new Set();
+  for (const finding of Array.isArray(lineageFindings) ? lineageFindings : []) {
+    ids.add(finding.nodeId || finding.target || finding.code || 'workspace');
+  }
+  return ids.size;
+}
+
+function auditItemMatchesQuery(item = {}, query = '') {
+  return [
+    item.title,
+    item.path,
+    item.schemaId,
+    item.moduleId,
+    item.status,
+    item.readState,
+    item.validationState,
+    item.validationCoverage,
+    item.schemaCoverage,
+    item.bodyAvailability,
+    item.sourceLabel,
+    ...(item.findings || []).flatMap((finding) => [finding.code, finding.message, finding.severity])
+  ].some((value) => String(value || '').toLowerCase().includes(query));
+}

package/src/workspaces/workspace.candidates.js

@@ -0,0 +1,149 @@
+import { addConfiguredSourceToWorkspace, workspaceSourceInputsFromMarkdown } from './workspace.entrypoints.js';
+import { replaceNonDraftWorkspaceSet } from './workspace.openSemantics.js';
+export function findWorkspaceCandidate(workspace = {}, candidateIdOrPath = '') {
+  const key = String(candidateIdOrPath || '').trim();
+  const canonical = canonicalizeLocalPath(key);
+  return (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : []).find((candidate) => {
+    return candidate.id === key || canonicalizeLocalPath(candidate.path || '') === canonical;
+  }) || null;
+}
+
+export function openWorkspaceCandidate(lifecycle, state, workspaceId = '', candidateIdOrPath = '', options = {}) {
+  if (!lifecycle) return { ok: false, error: 'lifecycle.missing', state };
+  const sourceWorkspace = (Array.isArray(state?.workspaces) ? state.workspaces : [])
+    .find((workspace) => workspace.id === (workspaceId || state.activeWorkspaceId));
+  if (!sourceWorkspace) return { ok: false, error: 'workspace.not.found', state };
+  const candidate = findWorkspaceCandidate(sourceWorkspace, candidateIdOrPath);
+  if (!candidate) return { ok: false, error: 'workspace.candidate.not.found', state };
+  const sourceInputs = workspaceSourceInputsFromMarkdown(candidate.markdown || '', options.parseWorkspaceConfig);
+  const opened = lifecycle.openWorkspaceFromMarkdown?.(state, candidate.markdown || '', {
+    title: candidate.title || workspaceTitleFromMarkdown(candidate.markdown || '') || candidate.path || 'Imported workspace',
+    path: candidate.path,
+    sourceMode: candidate.sourceMode || 'local-workspace-file',
+    importedFromWorkspaceId: sourceWorkspace.id || '',
+    importedFromWorkspaceTitle: sourceWorkspace.title || sourceWorkspace.name || ''
+  }, options);
+  if (!opened?.ok) return opened || { ok: false, error: 'workspace.open.failed', state };
+  let nextState = opened.state;
+  let workspace = lifecycle.activeWorkspace?.(nextState);
+  let contextReference = null;
+  if (workspace) {
+    contextReference = attachOpenedWorkspaceContextReference(workspace, sourceWorkspace, candidate, options);
+    workspace.importLog = Array.isArray(workspace.importLog) ? workspace.importLog : [];
+    workspace.workspaceImport = Object.assign({}, workspace.workspaceImport || {}, {
+      openedFromWorkspaceId: sourceWorkspace.id || '',
+      openedFromWorkspaceTitle: sourceWorkspace.title || sourceWorkspace.name || '',
+      openedCandidatePath: candidate.path || '',
+      mode: sourceInputs.length ? 'workspace-candidate-entrypoint-opened' : 'workspace-candidate-opened',
+      contextReferenceId: contextReference.id || '',
+      ownedMaterialPolicy: 'opened-workspace-owns-selected-workspace-only'
+    });
+    workspace.importLog.unshift({ kind: sourceInputs.length ? 'workspace-candidate-entrypoint-opened' : 'workspace-candidate-opened', fromWorkspaceId: sourceWorkspace.id, fromWorkspaceTitle: sourceWorkspace.title || sourceWorkspace.name || '', path: candidate.path || '', contextReferenceId: contextReference.id || '', ownedMaterialPolicy: 'reference-only', entrypointSources: sourceInputs.length, at: nowIso(options) });
+  }
+  const preparedInputs = [];
+  for (const sourceInput of sourceInputs) {
+    if (!workspace?.id) break;
+    const added = addConfiguredSourceToWorkspace(lifecycle, nextState, workspace.id, sourceInput, { discoveryState: 'deferred' });
+    if (!added?.ok) continue;
+    nextState = added.state;
+    workspace = (Array.isArray(nextState?.workspaces) ? nextState.workspaces : []).find((item) => item.id === workspace.id) || lifecycle.activeWorkspace?.(nextState);
+    preparedInputs.push(Object.assign({}, sourceInput, { workspaceId: workspace?.id || '', sourceId: added.source?.id || sourceInput.sourceId || '' }));
+  }
+  const targetWorkspaceId = workspace?.id || opened.workspace?.id || '';
+  const replaced = replaceNonDraftWorkspaceSet(nextState, [targetWorkspaceId]);
+  nextState = replaced.state;
+  workspace = (Array.isArray(nextState?.workspaces) ? nextState.workspaces : []).find((item) => item.id === targetWorkspaceId) || workspace || opened.workspace;
+  return Object.assign({}, opened, { state: nextState, workspace, candidate, sourceInputs: preparedInputs, contextReference, openedEntrypointWorkspace: Boolean(preparedInputs.length), openBoundary: replaced.report });
+}
+
+export function mergeWorkspaceCandidate(lifecycle, state, workspaceId = '', candidateIdOrPath = '', options = {}) {
+  if (!lifecycle) return { ok: false, error: 'lifecycle.missing', state };
+  const next = lifecycle.cloneState?.(state) || structuredClone(state);
+  const workspace = (Array.isArray(next?.workspaces) ? next.workspaces : [])
+    .find((item) => item.id === (workspaceId || next.activeWorkspaceId));
+  if (!workspace) return { ok: false, error: 'workspace.not.found', state };
+  const candidate = findWorkspaceCandidate(workspace, candidateIdOrPath);
+  if (!candidate) return { ok: false, error: 'workspace.candidate.not.found', state };
+  const path = canonicalizeLocalPath(candidate.path || 'workspace.workspace.md');
+  const merged = Object.assign({}, candidate, { mergedAt: nowIso(options), mergeMode: 'metadata-context', mergedIntoWorkspaceId: workspace.id || '', mergedIntoWorkspaceTitle: workspace.title || workspace.name || '' });
+  workspace.workspaceMergedEntries = Array.isArray(workspace.workspaceMergedEntries) ? workspace.workspaceMergedEntries.slice() : [];
+  const idx = workspace.workspaceMergedEntries.findIndex((item) => canonicalizeLocalPath(item.path || '') === path);
+  if (idx >= 0) workspace.workspaceMergedEntries[idx] = merged;
+  else workspace.workspaceMergedEntries.unshift(merged);
+  workspace.workspaceMergeCandidates = (Array.isArray(workspace.workspaceMergeCandidates) ? workspace.workspaceMergeCandidates : [])
+    .filter((item) => canonicalizeLocalPath(item.path || '') !== path);
+  workspace.importLog = Array.isArray(workspace.importLog) ? workspace.importLog : [];
+  workspace.importLog.unshift({ kind: 'workspace-merge-applied', path, title: candidate.title || '', intoWorkspaceId: workspace.id || '', at: merged.mergedAt });
+  next.activeWorkspaceId = workspace.id;
+  return { ok: true, workspace, candidate: merged, state: next, merge: { mode: 'metadata-context', targetWorkspaceId: workspace.id || '', targetWorkspaceTitle: workspace.title || workspace.name || '' } };
+}
+
+function attachOpenedWorkspaceContextReference(targetWorkspace, sourceWorkspace, openedCandidate, options = {}) {
+  const openedPath = canonicalizeLocalPath(openedCandidate?.path || '');
+  targetWorkspace.records = Array.isArray(targetWorkspace.records) ? targetWorkspace.records : [];
+  targetWorkspace.assets = Array.isArray(targetWorkspace.assets) ? targetWorkspace.assets : [];
+  targetWorkspace.workspaceMergeCandidates = Array.isArray(targetWorkspace.workspaceMergeCandidates) ? targetWorkspace.workspaceMergeCandidates : [];
+  targetWorkspace.workspaceMergedEntries = Array.isArray(targetWorkspace.workspaceMergedEntries) ? targetWorkspace.workspaceMergedEntries : [];
+  const reference = {
+    schema: 'tiinex.workspace.context-reference.v1',
+    id: contextReferenceId(sourceWorkspace, openedCandidate),
+    relation: 'opened-from-workspace-candidate',
+    sourceWorkspaceId: sourceWorkspace?.id || '',
+    sourceWorkspaceTitle: sourceWorkspace?.title || sourceWorkspace?.name || '',
+    candidateId: openedCandidate?.id || '',
+    candidatePath: openedPath,
+    candidateTitle: openedCandidate?.title || workspaceTitleFromMarkdown(openedCandidate?.markdown || '') || openedPath,
+    ownedMaterialPolicy: 'reference-only',
+    note: 'Opened workspace may use the origin/package workspace as lineage or recovery context, but sibling records, assets, source rows, and workspace candidates are not cloned as owned material.',
+    counts: {
+      sourceRecords: Array.isArray(sourceWorkspace?.records) ? sourceWorkspace.records.length : 0,
+      sourceAssets: Array.isArray(sourceWorkspace?.assets) ? sourceWorkspace.assets.length : 0,
+      sourceRows: Array.isArray(sourceWorkspace?.sources) ? sourceWorkspace.sources.length : 0,
+      sourceWorkspaceCandidates: Array.isArray(sourceWorkspace?.workspaceMergeCandidates) ? sourceWorkspace.workspaceMergeCandidates.length : 0,
+      siblingWorkspaceCandidates: Array.isArray(sourceWorkspace?.workspaceMergeCandidates) ? sourceWorkspace.workspaceMergeCandidates.filter((item) => canonicalizeLocalPath(item.path || '') !== openedPath).length : 0
+    },
+    at: nowIso(options)
+  };
+  targetWorkspace.contextReferences = Array.isArray(targetWorkspace.contextReferences) ? targetWorkspace.contextReferences.filter((item) => item?.id !== reference.id) : [];
+  targetWorkspace.contextReferences.unshift(reference);
+  targetWorkspace.workspaceContext = Object.assign({}, targetWorkspace.workspaceContext || {}, {
+    schema: 'tiinex.workspace.context.v1',
+    openedFromContextReferenceId: reference.id,
+    ownedMaterialPolicy: reference.ownedMaterialPolicy,
+    sourceWorkspaceId: reference.sourceWorkspaceId
+  });
+  return reference;
+}
+
+function contextReferenceId(sourceWorkspace = {}, openedCandidate = {}) {
+  const sourceId = String(sourceWorkspace?.id || 'workspace').trim() || 'workspace';
+  const candidateKey = canonicalizeLocalPath(openedCandidate?.path || openedCandidate?.id || 'workspace.workspace.md') || 'workspace.workspace.md';
+  return `workspace-context:${sourceId}:${candidateKey}`;
+}
+
+function workspaceTitleFromMarkdown(markdown = '') {
+  const text = String(markdown || '');
+  const browserTitle = text.match(/^\s*-\s*Browser Title:\s*(.+)$/mi)?.[1]?.trim();
+  if (browserTitle) return stripMarkdown(browserTitle);
+  const heading = text.match(/^#\s+(.+)\s*$/m)?.[1]?.trim();
+  return stripMarkdown(heading || '');
+}
+
+function stripMarkdown(value = '') {
+  return String(value || '').replace(/^\[([^\]]+)\]\([^)]*\)$/, '$1').trim();
+}
+
+function canonicalizeLocalPath(inputPath) {
+  let p = String(inputPath || '').trim().replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+  const out = [];
+  for (const part of p.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') out.pop();
+    else out.push(part);
+  }
+  return out.join('/');
+}
+
+function nowIso(options = {}) {
+  return typeof options.clock === 'function' ? options.clock() : new Date().toISOString();
+}

package/src/workspaces/workspace.config.js

@@ -0,0 +1,153 @@
+(function attachWorkspaceConfig(global) {
+  'use strict';
+
+  const WORKSPACE_ENTRYPOINT_FIELD_ALIASES = ['repoFilesDiscovery', 'issueDiscovery', 'issueUrl'];
+
+  const DEFAULT_WORKSPACE_MARKDOWN = "# Continuity Context\n\n- Envelope Schema: [tiinex.root.v1](https://github.com/Tiinex/docs/blob/7aecdb99551c4b6850665cdee418f0b9907d9616/.topics/.schemas/tiinex.root.v1.schema.md)\n- Current\n  - Current Schema: [tiinex.workspace.v1](../.schemas/tiinex.workspace.v1.schema.md)\n  - Created At: 2026-06-16 00:00:00\n  - Why: Defines a portable multi-lineage workspace entrypoint.\n  - Summary: Opens the Tiinex docs workspace and declares the default viewer discovery lens.\n\n---\n\n# Tiinex Viewer\n\n## Viewer Identity\n\n- Icon: ../../assets/tiinex-logo-white-transparent.png\n- Browser Title: Tiinex\n- Home: https://github.com/Tiinex\n- Public Viewer URL: https://tiinex.dev/\n- Workspace Home: https://tiinex.dev/\n\n## Empty Stage\n\n- Subtitle: Every handoff starts somewhere\n- Subtitle: Start where the last thread ends\n- Subtitle: Leave enough for the next mind\n- Subtitle: A thread is waiting\n- Subtitle: Nothing starts from nothing\n\n## Schema Origins\n\n- [Tiinex docs schemas](https://github.com/Tiinex/docs/tree/master/.topics/.schemas)\n  - Kind: github-tree\n  - Repository: Tiinex/docs\n  - Ref: master\n  - Root Path: .topics/.schemas\n  - Trust Role: canonical-core\n\n- [Viewer local schemas](../../src/schemas)\n  - Kind: app-local\n  - Repository: Tiinex/site\n  - Root Path: src/schemas\n  - Trust Role: viewer-extension\n  - Purpose: app-specific schema projections and viewer-only modules\n\n## Workspace Discovery\n\n- [Tiinex docs workspaces](https://github.com/Tiinex/docs)\n  - Kind: github-tree\n  - Ref: master\n  - Root Path: .topics\n  - Match: *.workspace.md\n  - Label: Tiinex docs workspaces\n  - Open Behavior: chooser\n\n## Workspace Entrypoints\n\n### Tiinex docs\n\n- Source Kind: github-tree\n- Repository: Tiinex/docs\n- Ref: master\n- Root Path: .topics\n- Repo Files Discovery: on\n- Issue Discovery: on\n- Issue URL: https://github.com/Tiinex/docs/issues/9\n- Default View: feed\n- Default Filter: all\n\n## Repository Mirrors\n\n### Tiinex docs\n\n- Repository: Tiinex/docs\n- URL: https://github.com/Tiinex/docs.git\n\n### Tiinex ai-provenance\n\n- Repository: Tiinex/ai-provenance\n- URL: https://github.com/Tiinex/ai-provenance.git\n\n## Repository Transports\n\n### Shared browser Git proxy\n\n- Kind: git-proxy\n- Match: github.com/*\n- Proxy: https://cors.isomorphic-git.org\n- Activation: manual\n- Note: Shared test proxy; use only when explicitly requested or replaced by a hosted workspace proxy.\n\n## Help\n\n### What is this view?\n\nThis workspace opens Tiinex markdown artifacts so an external reviewer and their LLM helpers can inspect continuity, source material, integrity signals, and continuation paths.\n\n### What should I check first?\n\nStart with what is loaded.\n\nCheck the workspace source, then inspect the visible badges. Treat integrity mismatch, missing integrity, unknown schema, and local-only material as review signals, not automatic failure.\n\n### What should I trust?\n\nTrust only what the artifact and its sources actually show.\n\nUse `Source` to inspect where material came from, `Markdown` to read the artifact, `Open` to inspect the selected node, and `Continue` only when the next step is clear enough to preserve.\n\n### What should an LLM preserve?\n\nDo not collapse Parent and Origin.\n\nParent is the declared continuity edge. Origin is provenance for where the material came from. If either is missing or weak, say so rather than filling the gap.\n\n### What should I send back?\n\nA useful validation note names the selected artifact, the source inspected, the observed signal, and the smallest next correction or continuation.\n\n---\n\n# Continuity Integrity\n\n- [sha256-base64url-c14n-v1](https://github.com/Tiinex/docs/blob/3466e50d739a9ba65319297cef79c6b09844b1d7/.topics/.validators/sha256-base64url-c14n-v1.validator.md)\n  - Towards: [viewer.workspace.md](viewer.workspace.md)\n  - Value: 6H8m4TbXAerVosJMfQWwGw9diSTKhp2rbaTqiClVP7k\n";
+
+  function parseWorkspaceConfig(markdown) {
+    const text = String(markdown || '');
+    return {
+      source: { kind: 'workspace-md', path: '.topics/.workspaces/viewer.workspace.md', fallback: !text.trim() },
+      viewerIdentity: parseViewerIdentity(text),
+      emptyStage: parseEmptyStage(text),
+      schemaOrigins: parseLinkedGroups(markdownSection(text, 'Schema Origins')),
+      workspaceDiscovery: parseLinkedGroups(markdownSection(text, 'Workspace Discovery')),
+      workspaceEntrypoints: parseHeadingGroups(markdownSection(text, 'Workspace Entrypoints')),
+      repositoryMirrors: parseHeadingGroups(markdownSection(text, 'Repository Mirrors')),
+      repositoryTransports: parseHeadingGroups(markdownSection(text, 'Repository Transports')),
+      help: parseHelp(markdownSection(text, 'Help'))
+    };
+  }
+
+  function createDefaultWorkspaceConfig(markdown) {
+    return parseWorkspaceConfig(markdown || DEFAULT_WORKSPACE_MARKDOWN);
+  }
+
+  function parseViewerIdentity(markdown) {
+    const map = sectionKeyValueMap(markdownSection(markdown, 'Viewer Identity'));
+    return {
+      icon: firstValue(map, ['Icon'], '../../assets/tiinex-logo-white-transparent.png'),
+      browserTitle: firstValue(map, ['Browser Title', 'Title'], 'Tiinex'),
+      home: firstValue(map, ['Home'], ''),
+      publicViewerUrl: firstValue(map, ['Public Viewer URL'], ''),
+      workspaceHome: firstValue(map, ['Workspace Home', 'Home'], '')
+    };
+  }
+
+  function parseEmptyStage(markdown) {
+    const map = sectionKeyValueMap(markdownSection(markdown, 'Empty Stage'));
+    const subtitles = valuesFor(map, ['Subtitle', 'Subtitles']).filter(Boolean);
+    return {
+      subtitles: subtitles.length ? subtitles : ['Everything starts from somewhere.'],
+      dropBehavior: firstValue(map, ['Empty Drop Behavior'], 'create-or-open-local-workspace'),
+      copyLinkBehavior: firstValue(map, ['Empty Copy Link Behavior'], 'clean-url')
+    };
+  }
+
+  function emptyStageSubtitle(config, cursor = 0) {
+    const subtitles = Array.isArray(config?.emptyStage?.subtitles) && config.emptyStage.subtitles.length
+      ? config.emptyStage.subtitles
+      : ['Everything starts from somewhere.'];
+    return subtitles[Math.abs(Number(cursor) || 0) % subtitles.length];
+  }
+
+  function markdownSection(markdown, heading) {
+    const lines = String(markdown || '').split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`.toLowerCase());
+    if (start < 0) return '';
+    const out = [];
+    for (let index = start + 1; index < lines.length; index += 1) {
+      if (/^##\s+/.test(lines[index])) break;
+      out.push(lines[index]);
+    }
+    return out.join('\n');
+  }
+
+  function parseLinkedGroups(section) {
+    const lines = String(section || '').split(/\r?\n/);
+    const groups = [];
+    let current = null;
+    lines.forEach((line) => {
+      const top = line.match(/^\s*[-*]\s+\[(.+?)\]\((.+?)\)\s*$/);
+      const child = line.match(/^\s{2,}[-*]\s+([^:]+):\s*(.+?)\s*$/);
+      if (top) {
+        current = { title: top[1].trim(), href: top[2].trim() };
+        groups.push(current);
+      } else if (current && child) {
+        current[toCamel(child[1])] = cleanListValue(child[2]);
+      }
+    });
+    return groups;
+  }
+
+  function parseHeadingGroups(section) {
+    const lines = String(section || '').split(/\r?\n/);
+    const groups = [];
+    let current = null;
+    lines.forEach((line) => {
+      const heading = line.match(/^###\s+(.+?)\s*$/);
+      const item = line.match(/^\s*[-*]\s+([^:]+):\s*(.+?)\s*$/);
+      if (heading) {
+        current = { name: heading[1].trim() };
+        groups.push(current);
+      } else if (current && item) {
+        const key = toCamel(item[1]);
+        const value = cleanListValue(item[2]);
+        if (!value) return;
+        if (current[key] && WORKSPACE_ENTRYPOINT_FIELD_ALIASES.includes(key)) {
+          current[key] = `${current[key]}\n${value}`;
+        } else {
+          current[key] = value;
+        }
+      }
+    });
+    return groups;
+  }
+
+  function parseHelp(section) {
+    return parseHeadingGroups(section).map((group) => {
+      const lines = markdownSubsection(section, group.name).split(/\r?\n/).filter(Boolean);
+      return { question: group.name, body: lines.join('\n').trim() };
+    });
+  }
+
+  function markdownSubsection(section, heading) {
+    const lines = String(section || '').split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `### ${heading}`.toLowerCase());
+    if (start < 0) return '';
+    const out = [];
+    for (let index = start + 1; index < lines.length; index += 1) {
+      if (/^###\s+/.test(lines[index])) break;
+      out.push(lines[index]);
+    }
+    return out.join('\n').trim();
+  }
+
+  function sectionKeyValueMap(section) {
+    const map = new Map();
+    String(section || '').split(/\r?\n/).forEach((line) => {
+      const match = line.match(/^\s*[-*]\s+([^:]+):\s*(.+?)\s*$/);
+      if (!match) return;
+      const key = match[1].trim();
+      const value = cleanListValue(match[2]);
+      if (!map.has(key)) map.set(key, []);
+      if (value) map.get(key).push(value);
+    });
+    return map;
+  }
+
+  function valuesFor(map, keys) { return keys.flatMap((key) => map.get(key) || []); }
+  function firstValue(map, keys, fallback = '') { return valuesFor(map, keys)[0] || fallback; }
+  function cleanListValue(value) { return String(value || '').replace(/^\[(.+?)\]\(.+?\)$/u, '$1').trim(); }
+  function toCamel(value) { return String(value || '').trim().toLowerCase().replace(/[^a-z0-9]+([a-z0-9])/g, (_m, c) => c.toUpperCase()); }
+
+  global.TiinexWorkspaceConfig = {
+    DEFAULT_WORKSPACE_MARKDOWN,
+    createDefaultWorkspaceConfig,
+    emptyStageSubtitle,
+    parseWorkspaceConfig,
+    parseHeadingGroups,
+    parseLinkedGroups
+  };
+})(typeof window !== 'undefined' ? window : globalThis);

package/src/workspaces/workspace.configuredSource.js

@@ -0,0 +1,68 @@
+import '../sources/source.identity.js';
+import { normalizeExplicitFileRefs } from '@tiinex/core/sources/source.explicitTargets.js';
+
+export function makeConfiguredSource(input = {}, options = {}, runtime = {}) {
+  const repo = String(input.repository || input.repo || '').trim();
+  const label = String(input.label || repo || 'Source').trim();
+  const rootPath = String(input.rootPath || input.config?.rootPath || '.topics').trim() || '.topics';
+  const ref = String(input.ref || input.config?.ref || '').trim();
+  const requestedRef = Object.prototype.hasOwnProperty.call(input, 'requestedRef') ? String(input.requestedRef || '').trim() : String(input.config?.requestedRef ?? ref).trim();
+  const materializedCommit = exactCommit(input.materializedCommit || input.config?.materializedCommit);
+  const issueUrls = input.issueUrls || input.config?.issueUrls || '';
+  const explicitFileRefs = normalizeExplicitFileRefs(input.explicitFileRefs ?? input.fileRefs ?? input.config?.explicitFileRefs ?? input.config?.fileRefs ?? []);
+  const requestedSurfaces = input.requestedSurfaces ? Object.assign({}, input.requestedSurfaces) : {
+    repoFiles: { requested: Boolean(input.repoDiscovery) },
+    explicitFiles: { requested: Boolean(explicitFileRefs.length), requestedCount: explicitFileRefs.length },
+    issueSnapshots: { requested: Boolean(input.issueDiscovery || issueUrls) }
+  };
+  return {
+    id: configuredSourceIdForWorkspace(Object.assign({}, input, { repo, ref, rootPath }), runtime.existingSources, options),
+    kind: input.kind || runtime.configuredSourceKind || 'github-tree', adapterId: input.adapterId || runtime.githubAdapterId || 'github', sourceKind: input.sourceKind || runtime.githubRepoSourceKind || 'github.repo',
+    label, repo, ref, requestedRef, materializedCommit, rootPath, config: { repo, ref, requestedRef, rootPath, issueUrls, explicitFileRefs: explicitFileRefs.slice() }, count: Number(input.count || 0),
+    boundary: 'explicit source boundary; no material is trusted until loaded', transportLabel: input.transportLabel || options.transportLabel || 'Source Pages mirror', transportRefreshTier: input.transportRefreshTier || input.preferredTransportTier || '',
+    transportPlan: input.transportPlan ? Object.assign({}, input.transportPlan) : undefined, transportOutcome: input.transportOutcome ? Object.assign({}, input.transportOutcome) : undefined,
+    governanceBoundary: input.governanceBoundary ? Object.assign({}, input.governanceBoundary) : undefined, transportTiers: input.transportTiers ? Object.assign({}, input.transportTiers) : undefined,
+    repoDiscovery: Boolean(input.repoDiscovery), issueDiscovery: Boolean(input.issueDiscovery), issueUrls, explicitFileRefs,
+    workspaceMatch: input.workspaceMatch || input.config?.workspaceMatch || '', appConfigPlan: input.appConfigPlan || input.config?.appConfigPlan || '', openBehavior: input.openBehavior || input.config?.openBehavior || '', preferredDisplay: input.preferredDisplay || input.config?.preferredDisplay || '',
+    requestedSurfaces, surfaces: Object.assign({}, input.surfaces || input.surfaceState || {}), discoveryState: runtime.normalizeSourceDiscoveryState ? runtime.normalizeSourceDiscoveryState(input.discoveryState, 'deferred') : (input.discoveryState || 'deferred'),
+    closeable: input.closeable !== false, loadable: input.loadable !== false
+  };
+}
+
+function exactCommit(value = '') { const commit = String(value || '').trim(); return /^[0-9a-f]{40}$/i.test(commit) ? commit : ''; }
+
+export function configuredSourceIdForWorkspace(input = {}, existingSources = [], options = {}) {
+  const sources = Array.isArray(existingSources) ? existingSources : [];
+  const requestedId = String(input.id || '').trim();
+  const authoritativeRefinement = options?.sourceIdentityPolicy === 'refine-existing'
+    ? sources.find((source) => String(source?.id || '') === requestedId)
+    : null;
+  if (authoritativeRefinement?.id) return authoritativeRefinement.id;
+  const boundaryKey = globalThis.TiinexSourceIdentity?.configuredSourceBoundaryKey?.(input) || '';
+  const sameBoundary = boundaryKey
+    ? sources.find((source) => globalThis.TiinexSourceIdentity?.configuredSourceBoundaryKey?.(source) === boundaryKey)
+    : null;
+  if (sameBoundary?.id) return sameBoundary.id;
+
+  const generated = input.id || globalThis.TiinexSourceIdentity?.makeConfiguredSourceId?.(input) || `github:${String(input.repository || input.repo || 'source').trim().toLowerCase()}`;
+  const collision = sources.find((source) => String(source?.id || '') === generated);
+  if (!collision) return generated;
+
+  const suffix = stableBoundarySuffix(boundaryKey || JSON.stringify(input));
+  let candidate = `${generated}--boundary-${suffix}`;
+  let serial = 2;
+  while (sources.some((source) => String(source?.id || '') === candidate)) {
+    candidate = `${generated}--boundary-${suffix}-${serial}`;
+    serial += 1;
+  }
+  return candidate;
+}
+
+function stableBoundarySuffix(value = '') {
+  let hash = 2166136261;
+  for (const char of String(value || '')) {
+    hash ^= char.charCodeAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(36);
+}

package/src/workspaces/workspace.discoveryProgress.js

@@ -0,0 +1,34 @@
+export function setWorkspaceDiscoveryProgress(state = {}, workspaceId = '', progress = {}) {
+  const next = structuredClone(state || {});
+  const targetId = workspaceId || next.activeWorkspaceId;
+  const workspace = (next.workspaces || []).find((item) => item.id === targetId);
+  if (!workspace) return { ok: false, error: 'workspace.not.found', state };
+  const sourceId = String(progress.sourceId || '').trim();
+  const hasMeasuredPercent = progress.percent != null && Number.isFinite(Number(progress.percent));
+  const quantified = progress.quantified === false ? false : hasMeasuredPercent;
+  workspace.discoveryProgress = {
+    sourceId,
+    phase: progress.phase || 'source-materialization',
+    label: progress.label || 'Source materialization running',
+    percent: quantified ? Math.max(0, Math.min(100, Number(progress.percent))) : null,
+    quantified,
+    active: progress.active !== false
+  };
+  if (progress.loaded != null) workspace.discoveryProgress.loaded = Number(progress.loaded || 0);
+  if (progress.total != null) workspace.discoveryProgress.total = Number(progress.total || 0);
+  const source = (workspace.sources || []).find((item) => item.id === sourceId);
+  if (source) source.discoveryState = progress.discoveryState || (progress.active === false ? 'failed' : 'loading');
+  next.activeWorkspaceId = workspace.id;
+  return { ok: true, workspace, state: next };
+}
+
+export function clearWorkspaceDiscoveryProgress(state = {}, workspaceId = '', sourceId = '') {
+  const next = structuredClone(state || {});
+  const targetId = workspaceId || next.activeWorkspaceId;
+  const workspace = (next.workspaces || []).find((item) => item.id === targetId);
+  if (!workspace) return { ok: false, error: 'workspace.not.found', state };
+  const clean = String(sourceId || '').trim();
+  if (!clean || workspace.discoveryProgress?.sourceId === clean) workspace.discoveryProgress = null;
+  next.activeWorkspaceId = workspace.id;
+  return { ok: true, workspace, state: next };
+}