truthmark 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.de.md CHANGED
@@ -194,6 +194,7 @@ Wenn der Agent funktionalen Code ändert, wirkt Truth Sync als Abschlusskontroll
194
194
  | Local-first-Betrieb | Benötigt keinen gehosteten Dienst, Daemon, keine Datenbank und keinen MCP-Server. |
195
195
  | Sicherere Schreibgrenzen | Trennt code-first, doc-first, read-only und doc-only Workflows. |
196
196
  | Validierung | Meldet Probleme bei Routing, Autorität, Frontmatter, Links, generierten Oberflächen, Branch-Scope, Freshness und Coverage. |
197
+ | Optionales Portal | Erzeugt eine festgeschriebene statische HTML-Präsentationssite aus Markdown-Truth-Dokumenten, wenn es ausdrücklich aktiviert und angefragt wird. |
197
198
 
198
199
  ## Visueller Überblick
199
200
 
@@ -326,6 +327,7 @@ Sie werden von Agenten oder Agenten-Hosts während der Repository-Arbeit genutzt
326
327
  | Truth Preview | read-only | Der Agent vor Änderungen wahrscheinliches Routing einschätzen muss. | Liest nur. Autorisiert keine Schreibzugriffe. |
327
328
  | Truth Realize | doc-first | Produkt- oder Architektur-Truth-Dokumente führen und Code daran angepasst werden soll. | Aktualisiert nur Code. Der Agent darf die Truth-Dokumente, die er realisiert, nicht bearbeiten. |
328
329
  | Truth Check | audit-first | Ein Reviewer oder Agent die Gesundheit der Repository-Wahrheit auditieren muss. | Auditiert und berichtet. |
330
+ | Truthmark Portal | presentation-only | Ein Mensch ausdrücklich eine durchsuchbare statische HTML-Portalansicht über Repository-Truth-Dokumente anfordert. | Schreibt generierte nicht-kanonische statische Dateien nur unter dem konfigurierten Portal-Ausgabeverzeichnis. |
329
331
 
330
332
  ### Wichtige Unterscheidung
331
333
 
@@ -437,6 +439,35 @@ Sie sind keine Quellen der Wahrheit.
437
439
 
438
440
  Strukturierte Ausgabe ist mit `--json` verfügbar, wo sie unterstützt wird.
439
441
 
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal ist ein optionaler Präsentations-Workflow für Teams, die eine menschenlesbare Site über ihren festgeschriebenen Truth-Dokumenten möchten.
445
+
446
+ Er ist bewusst vom Kern-Truth-Workflow getrennt:
447
+
448
+ - Markdown-Truth-Dokumente bleiben kanonisch.
449
+ - Generiertes Portal-HTML dient nur der Präsentation.
450
+ - Portal wird nur manuell ausgeführt; es läuft nicht als Completion-Gate, Truth-Sync-Schritt, `truthmark check`-Schritt oder automatischer Post-Change-Hook.
451
+ - Portal-Schreibzugriffe bleiben im konfigurierten Ausgabeverzeichnis, sofern der Nutzer den Scope nicht ausdrücklich ändert.
452
+ - Generierte Seiten sollten lokale Assets, Quellen-Provenance und einen sichtbaren Markdown-ist-kanonisch-Hinweis verwenden.
453
+
454
+ Aktiviere es mit dem namespaced Config-Block:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Dann erneut ausführen:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
468
+
469
+ Wenn aktiviert, installiert Truthmark host-native Portal-Workflow-Oberflächen für die konfigurierten Plattformen, etwa `/truthmark-portal` oder `/truthmark:portal` je nach Agenten-Host.
470
+
440
471
  ## Konfiguration
441
472
 
442
473
  Truthmark ist config-first.
@@ -471,6 +502,7 @@ Wichtige Config-Bereiche sind:
471
502
  | `docs.routing.area_files_root` | Verzeichnis für delegierte untergeordnete Routendateien. |
472
503
  | `docs.routing.default_area` | Dateiname des initial erzeugten untergeordneten Routings ohne Erweiterung. |
473
504
  | `docs.routing.max_delegation_depth` | Aktuelle maximale Routing-Delegationstiefe. |
505
+ | `truthmark-portal` | Optionale manuelle Präsentations-Workflow-Einstellungen: `enabled`, `output` und `template`. |
474
506
  | `authority` | Geordnete kanonische Dokumente und Globs, die als Repository-Truth-Autorität dienen. |
475
507
  | `instruction_targets` | Dateien, die gemeinsam verwaltete Instruktionsblöcke erhalten, etwa `AGENTS.md`. |
476
508
  | `frontmatter.required` | Metadatenfelder, die bei Fehlen Error-Diagnostik erzeugen. |
@@ -632,6 +664,21 @@ truthmark impact --base main
632
664
  truthmark context --workflow truth-sync --base main --format markdown
633
665
  ```
634
666
 
667
+ ### Optionalen Portal-Workflow aktivieren
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Bitte den Agenten-Host anschließend ausdrücklich, den installierten Portal-Workflow auszuführen, wenn die statische Präsentationssite erzeugt oder aktualisiert werden soll.
681
+
635
682
  ## Projektstatus
636
683
 
637
684
  Truthmark V1 bietet derzeit:
@@ -650,6 +697,7 @@ Truthmark V1 bietet derzeit:
650
697
  - generierte Truth-Preview-Workflow-Oberflächen
651
698
  - generierte Truth-Realize-Workflow-Oberflächen
652
699
  - generierte Truth-Check-Workflow-Oberflächen
700
+ - optionale generierte Truthmark-Portal-Workflow-Oberflächen
653
701
  - Diagnostik für Route, Autorität, Entscheidungsstruktur, Frontmatter, Links, Freshness, generierte Oberflächen und Coverage
654
702
  - abgeleitete RepoIndex-, RouteMap-, ImpactSet- und ContextPack-Artefakte
655
703
  - host-spezifische Oberflächen für Codex, Claude Code, GitHub Copilot, OpenCode und Gemini CLI
@@ -712,7 +760,7 @@ Es ist nicht:
712
760
  - ein gehosteter Dienst
713
761
  - ein MCP-Server
714
762
  - eine Vektordatenbank
715
- - ein Generator für Dokumentations-Websites
763
+ - ein kanonischer Dokumentations-Website-Generator oder eine gehostete Docs-Plattform
716
764
  - ein CI- oder PR-Enforcement-Produkt
717
765
  - ein Ersatz für Tests, Code Review oder technische Führung
718
766
  - eine autonome Code-Rewrite-Engine
package/README.es.md CHANGED
@@ -194,6 +194,7 @@ Cuando el agente cambia código funcional, Truth Sync actúa como guarda de cier
194
194
  | Operación local-first | No requiere servicio alojado, demonio, base de datos ni servidor MCP. |
195
195
  | Límites de escritura más seguros | Separa flujos code-first, doc-first, read-only y doc-only. |
196
196
  | Validación | Reporta problemas de rutas, autoridad, frontmatter, enlaces, superficies generadas, alcance de rama, frescura y cobertura. |
197
+ | Portal opcional | Genera un sitio HTML estático confirmado desde documentos de verdad Markdown cuando se habilita y solicita explícitamente. |
197
198
 
198
199
  ## Resumen visual
199
200
 
@@ -326,6 +327,7 @@ Los usan agentes o hosts de agentes durante el trabajo en el repositorio. No son
326
327
  | Truth Preview | read-only | El agente necesita previsualizar rutas probables antes de editar. | Solo lee. No autoriza escrituras. |
327
328
  | Truth Realize | doc-first | Documentos de verdad de producto o arquitectura lideran y el código debe actualizarse para coincidir. | Actualiza solo código. El agente no debe editar los documentos de verdad que está realizando. |
328
329
  | Truth Check | audit-first | Un revisor o agente necesita auditar la salud de la verdad del repositorio. | Audita e informa. |
330
+ | Truthmark Portal | presentation-only | Una persona pide explícitamente un Portal HTML estático navegable sobre los documentos de verdad del repositorio. | Escribe solo archivos estáticos generados no canónicos bajo el directorio de salida Portal configurado. |
329
331
 
330
332
  ### Distinción importante
331
333
 
@@ -437,6 +439,35 @@ No son fuentes de verdad.
437
439
 
438
440
  La salida estructurada está disponible con `--json` donde se admite.
439
441
 
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal es un flujo opcional de presentación para equipos que quieren un sitio legible por personas sobre sus documentos de verdad confirmados.
445
+
446
+ Está separado deliberadamente del flujo central de verdad:
447
+
448
+ - Los documentos de verdad Markdown siguen siendo canónicos.
449
+ - El HTML Portal generado es solo presentación.
450
+ - Portal se ejecuta solo manualmente; no se ejecuta como puerta de finalización, paso de Truth Sync, paso de `truthmark check` ni hook automático post-change.
451
+ - Las escrituras de Portal permanecen dentro del directorio de salida configurado salvo que la persona cambie el alcance explícitamente.
452
+ - Las páginas generadas deben usar assets locales, procedencia de fuentes y un aviso visible de que Markdown es canónico.
453
+
454
+ Habilítalo con el bloque de configuración con espacio de nombres:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Luego vuelve a ejecutar:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
468
+
469
+ Cuando está habilitado, Truthmark instala superficies Portal host-native para las plataformas configuradas, como `/truthmark-portal` o `/truthmark:portal` según el host de agente.
470
+
440
471
  ## Configuración
441
472
 
442
473
  Truthmark es config-first.
@@ -471,6 +502,7 @@ Las áreas importantes de configuración incluyen:
471
502
  | `docs.routing.area_files_root` | Directorio para archivos de rutas secundarias delegadas. |
472
503
  | `docs.routing.default_area` | Nombre base de la ruta secundaria inicial generada. |
473
504
  | `docs.routing.max_delegation_depth` | Profundidad máxima actual de delegación de rutas. |
505
+ | `truthmark-portal` | Ajustes opcionales del flujo manual de presentación: `enabled`, `output` y `template`. |
474
506
  | `authority` | Documentos canónicos y globs ordenados usados como autoridad de verdad del repositorio. |
475
507
  | `instruction_targets` | Archivos que reciben bloques de instrucciones administrados compartidos, como `AGENTS.md`. |
476
508
  | `frontmatter.required` | Campos de metadatos que producen diagnósticos de error cuando faltan. |
@@ -632,6 +664,21 @@ truthmark impact --base main
632
664
  truthmark context --workflow truth-sync --base main --format markdown
633
665
  ```
634
666
 
667
+ ### Habilitar el flujo Portal opcional
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Luego pide explícitamente al host de agente que ejecute el flujo Portal instalado cuando quieras generar o refrescar el sitio estático de presentación.
681
+
635
682
  ## Estado del proyecto
636
683
 
637
684
  Truthmark V1 actualmente proporciona:
@@ -650,6 +697,7 @@ Truthmark V1 actualmente proporciona:
650
697
  - superficies generadas de flujo Truth Preview
651
698
  - superficies generadas de flujo Truth Realize
652
699
  - superficies generadas de flujo Truth Check
700
+ - superficies generadas opcionales de flujo Truthmark Portal
653
701
  - diagnósticos de rutas, autoridad, estructura de decisiones, frontmatter, enlaces, frescura, superficies generadas y cobertura
654
702
  - artefactos derivados RepoIndex, RouteMap, ImpactSet y ContextPack
655
703
  - superficies específicas de host para Codex, Claude Code, GitHub Copilot, OpenCode y Gemini CLI
@@ -712,7 +760,7 @@ No es:
712
760
  - un servicio alojado
713
761
  - un servidor MCP
714
762
  - una base de datos vectorial
715
- - un generador de sitios de documentación
763
+ - un generador canónico de sitios de documentación o plataforma de docs alojada
716
764
  - un producto de enforcement para CI o PR
717
765
  - un reemplazo de pruebas, revisión de código o liderazgo técnico
718
766
  - un motor autónomo de reescritura de código
package/README.md CHANGED
@@ -194,6 +194,7 @@ When the agent changes functional code, Truth Sync acts as the finish-time guard
194
194
  | Local-first operation | Requires no hosted service, daemon, database, or MCP server. |
195
195
  | Safer write boundaries | Separates code-first, doc-first, read-only, and doc-only workflows. |
196
196
  | Validation | Reports routing, authority, frontmatter, link, generated-surface, branch-scope, freshness, and coverage issues. |
197
+ | Optional Portal | Generates a committed static HTML presentation site from Markdown truth docs when explicitly enabled and requested. |
197
198
 
198
199
  ## Visual overview
199
200
 
@@ -326,6 +327,7 @@ They are used by agents or agent hosts during repository work. They are not top-
326
327
  | Truth Preview | read-only | The agent needs to preview likely routing before edits. | Reads only. Does not authorize writes. |
327
328
  | Truth Realize | doc-first | Product or architecture truth docs lead and code should be updated to match. | Updates code only. The agent must not edit the truth docs it is realizing. |
328
329
  | Truth Check | audit-first | A reviewer or agent needs to audit repository truth health. | Audits and reports. |
330
+ | Truthmark Portal | presentation-only | A human explicitly asks for a browsable static HTML Portal over repository truth docs. | Writes generated non-canonical static files only under the configured Portal output directory. |
329
331
 
330
332
  ### Important distinction
331
333
 
@@ -437,6 +439,35 @@ They are not sources of truth.
437
439
 
438
440
  Structured output is available with `--json` where supported.
439
441
 
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal is an optional presentation workflow for teams that want a human-readable site over their committed truth docs.
445
+
446
+ It is deliberately separate from the core truth workflow:
447
+
448
+ - Markdown truth docs remain canonical.
449
+ - Generated Portal HTML is presentation only.
450
+ - Portal is manual-only; it does not run as a completion gate, Truth Sync step, `truthmark check` step, or automatic post-change hook.
451
+ - Portal writes stay inside the configured output directory unless the user explicitly changes scope.
452
+ - Generated pages should use local assets, source provenance, and a visible Markdown-canonical disclaimer.
453
+
454
+ Enable it with the namespaced config block:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Then rerun:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
468
+
469
+ When enabled, Truthmark installs host-native Portal workflow surfaces for the configured platforms, such as `/truthmark-portal` or `/truthmark:portal` depending on the agent host.
470
+
440
471
  ## Configuration
441
472
 
442
473
  Truthmark is config-first.
@@ -471,6 +502,7 @@ Important config areas include:
471
502
  | `docs.routing.area_files_root` | Directory for delegated child route files. |
472
503
  | `docs.routing.default_area` | Initial scaffolded child route basename. |
473
504
  | `docs.routing.max_delegation_depth` | Current maximum route delegation depth. |
505
+ | `truthmark-portal` | Optional manual presentation workflow settings: `enabled`, `output`, and `template`. |
474
506
  | `authority` | Ordered canonical docs and globs used as repository truth authority. |
475
507
  | `instruction_targets` | Files that receive shared managed instruction blocks, such as `AGENTS.md`. |
476
508
  | `frontmatter.required` | Metadata fields that produce error diagnostics when missing. |
@@ -632,6 +664,21 @@ truthmark impact --base main
632
664
  truthmark context --workflow truth-sync --base main --format markdown
633
665
  ```
634
666
 
667
+ ### Enable the optional Portal workflow
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Then explicitly ask the agent host to run the installed Portal workflow when you want the static presentation site generated or refreshed.
681
+
635
682
  ## Project status
636
683
 
637
684
  Truthmark V1 currently provides:
@@ -650,6 +697,7 @@ Truthmark V1 currently provides:
650
697
  - generated Truth Preview workflow surfaces
651
698
  - generated Truth Realize workflow surfaces
652
699
  - generated Truth Check workflow surfaces
700
+ - optional generated Truthmark Portal workflow surfaces
653
701
  - route, authority, decision-structure, frontmatter, link, freshness, generated-surface, and coverage diagnostics
654
702
  - derived RepoIndex, RouteMap, ImpactSet, and ContextPack artifacts
655
703
  - host-specific surfaces for Codex, Claude Code, GitHub Copilot, OpenCode, and Gemini CLI
@@ -712,7 +760,7 @@ It is not:
712
760
  - a hosted service
713
761
  - an MCP server
714
762
  - a vector database
715
- - a documentation website generator
763
+ - a canonical documentation website generator or hosted docs platform
716
764
  - a CI or PR enforcement product
717
765
  - a replacement for tests, code review, or technical leadership
718
766
  - an autonomous code rewrite engine
package/README.ru.md CHANGED
@@ -194,6 +194,7 @@ truthmark check
194
194
  | Local-first работа | Не требует размещенного сервиса, daemon, базы данных или MCP-сервера. |
195
195
  | Более безопасные границы записи | Разделяет code-first, doc-first, read-only и doc-only workflows. |
196
196
  | Валидация | Сообщает о проблемах маршрутизации, authority, frontmatter, ссылок, generated surfaces, branch scope, freshness и coverage. |
197
+ | Опциональный Portal | Генерирует зафиксированный статический HTML-сайт презентации из Markdown-документов истины, когда он явно включен и запрошен. |
197
198
 
198
199
  ## Визуальный обзор
199
200
 
@@ -326,6 +327,7 @@ truthmark init
326
327
  | Truth Preview | read-only | Агенту нужно предварительно понять вероятный routing перед правками. | Только чтение. Не авторизует записи. |
327
328
  | Truth Realize | doc-first | Продуктовые или архитектурные документы истины ведут, и код нужно обновить под них. | Обновляет только код. Агент не должен редактировать документы истины, которые реализует. |
328
329
  | Truth Check | audit-first | Ревьюеру или агенту нужно проверить здоровье истины репозитория. | Аудитирует и сообщает. |
330
+ | Truthmark Portal | presentation-only | Человек явно просит доступный для просмотра статический HTML Portal по документам истины репозитория. | Пишет только сгенерированные неканонические статические файлы в настроенную директорию вывода Portal. |
329
331
 
330
332
  ### Важное различие
331
333
 
@@ -437,6 +439,35 @@ truthmark check
437
439
 
438
440
  Структурированный вывод доступен с `--json` там, где поддерживается.
439
441
 
442
+ ## Truthmark Portal
443
+
444
+ Truthmark Portal — опциональный презентационный workflow для команд, которым нужен человекочитаемый сайт поверх зафиксированных документов истины.
445
+
446
+ Он намеренно отделен от основного workflow истины:
447
+
448
+ - Markdown-документы истины остаются каноническими.
449
+ - Сгенерированный HTML Portal предназначен только для презентации.
450
+ - Portal запускается только вручную; он не выполняется как completion gate, шаг Truth Sync, шаг `truthmark check` или автоматический post-change hook.
451
+ - Записи Portal остаются внутри настроенной директории вывода, если пользователь явно не меняет scope.
452
+ - Сгенерированные страницы должны использовать локальные assets, provenance источников и видимое уведомление, что Markdown является каноническим источником.
453
+
454
+ Включите его namespaced config-блоком:
455
+
456
+ ```yaml
457
+ truthmark-portal:
458
+ enabled: true
459
+ output: docs/truthmark-portal
460
+ template: default
461
+ ```
462
+
463
+ Затем запустите снова:
464
+
465
+ ```bash
466
+ truthmark init
467
+ ```
468
+
469
+ Когда Portal включен, Truthmark устанавливает host-native Portal workflow surfaces для настроенных платформ, например `/truthmark-portal` или `/truthmark:portal` в зависимости от agent host.
470
+
440
471
  ## Конфигурация
441
472
 
442
473
  Truthmark работает config-first.
@@ -471,6 +502,7 @@ truthmark init
471
502
  | `docs.routing.area_files_root` | Директория для делегированных дочерних файлов маршрутов. |
472
503
  | `docs.routing.default_area` | Базовое имя начального scaffolded дочернего маршрута. |
473
504
  | `docs.routing.max_delegation_depth` | Текущая максимальная глубина делегирования routing. |
505
+ | `truthmark-portal` | Опциональные настройки ручного презентационного workflow: `enabled`, `output` и `template`. |
474
506
  | `authority` | Упорядоченные канонические docs и globs, используемые как authority истины репозитория. |
475
507
  | `instruction_targets` | Файлы, которые получают общие управляемые блоки инструкций, например `AGENTS.md`. |
476
508
  | `frontmatter.required` | Поля metadata, которые создают error diagnostics при отсутствии. |
@@ -632,6 +664,21 @@ truthmark impact --base main
632
664
  truthmark context --workflow truth-sync --base main --format markdown
633
665
  ```
634
666
 
667
+ ### Включить опциональный Portal workflow
668
+
669
+ ```yaml
670
+ truthmark-portal:
671
+ enabled: true
672
+ output: docs/truthmark-portal
673
+ template: default
674
+ ```
675
+
676
+ ```bash
677
+ truthmark init
678
+ ```
679
+
680
+ Затем явно попросите agent host выполнить установленный Portal workflow, когда нужно сгенерировать или обновить статический презентационный сайт.
681
+
635
682
  ## Статус проекта
636
683
 
637
684
  Truthmark V1 сейчас предоставляет:
@@ -650,6 +697,7 @@ Truthmark V1 сейчас предоставляет:
650
697
  - сгенерированные поверхности workflow Truth Preview
651
698
  - сгенерированные поверхности workflow Truth Realize
652
699
  - сгенерированные поверхности workflow Truth Check
700
+ - опциональные сгенерированные поверхности workflow Truthmark Portal
653
701
  - diagnostics для route, authority, decision-structure, frontmatter, links, freshness, generated-surface и coverage
654
702
  - производные артефакты RepoIndex, RouteMap, ImpactSet и ContextPack
655
703
  - host-specific поверхности для Codex, Claude Code, GitHub Copilot, OpenCode и Gemini CLI
@@ -712,7 +760,7 @@ Truthmark намеренно небольшой.
712
760
  - размещенным сервисом
713
761
  - MCP-сервером
714
762
  - векторной базой данных
715
- - генератором сайтов документации
763
+ - каноническим генератором сайтов документации или hosted docs platform
716
764
  - CI- или PR-enforcement продуктом
717
765
  - заменой tests, code review или technical leadership
718
766
  - автономным движком переписывания кода
package/README.zh.md CHANGED
@@ -196,6 +196,7 @@ truthmark check
196
196
  | 本地优先运行 | 不需要托管服务、守护进程、数据库或 MCP 服务器。 |
197
197
  | 更安全的写入边界 | 区分 code-first、doc-first、read-only 和 doc-only 工作流。 |
198
198
  | 验证 | 报告路由、权限边界、frontmatter、链接、生成表面、分支范围、freshness 和覆盖率问题。 |
199
+ | 可选 Portal | 在明确启用并请求时,从 Markdown 事实文档生成已提交的静态 HTML 展示站点。 |
199
200
 
200
201
  ## 视觉概览
201
202
 
@@ -328,6 +329,7 @@ truthmark init
328
329
  | Truth Preview | read-only | 代理需要在编辑前预览可能的路由。 | 只读。不授权写入。 |
329
330
  | Truth Realize | doc-first | 产品或架构事实文档在前,代码应更新以匹配它们。 | 只更新代码。代理不能编辑它正在实现的事实文档。 |
330
331
  | Truth Check | audit-first | 审查者或代理需要审计仓库事实健康状况。 | 审计并报告。 |
332
+ | Truthmark Portal | presentation-only | 人类明确要求为仓库事实文档生成可浏览的静态 HTML Portal。 | 只在配置的 Portal 输出目录下写入生成的非规范静态文件。 |
331
333
 
332
334
  ### 重要区别
333
335
 
@@ -439,6 +441,35 @@ truthmark check
439
441
 
440
442
  受支持位置可使用 `--json` 获取结构化输出。
441
443
 
444
+ ## Truthmark Portal
445
+
446
+ Truthmark Portal 是一个可选的展示工作流,适合想要基于已提交 truth 文档生成面向人的可读站点的团队。
447
+
448
+ 它有意与核心 truth 工作流分离:
449
+
450
+ - Markdown truth 文档仍然是规范来源。
451
+ - 生成的 Portal HTML 仅用于展示。
452
+ - Portal 只能手动运行;它不会作为完成门禁、Truth Sync 步骤、`truthmark check` 步骤或自动 post-change hook 运行。
453
+ - 除非用户明确改变范围,Portal 写入必须留在配置的输出目录内。
454
+ - 生成页面应使用本地 assets、来源 provenance,并显示 Markdown 规范来源免责声明。
455
+
456
+ 用这个命名空间配置块启用它:
457
+
458
+ ```yaml
459
+ truthmark-portal:
460
+ enabled: true
461
+ output: docs/truthmark-portal
462
+ template: default
463
+ ```
464
+
465
+ 然后重新运行:
466
+
467
+ ```bash
468
+ truthmark init
469
+ ```
470
+
471
+ 启用后,Truthmark 会为已配置平台安装宿主原生 Portal 工作流表面,例如 `/truthmark-portal` 或 `/truthmark:portal`,具体取决于代理宿主。
472
+
442
473
  ## 配置
443
474
 
444
475
  Truthmark 是 config-first。
@@ -473,6 +504,7 @@ truthmark init
473
504
  | `docs.routing.area_files_root` | 委托子路由文件目录。 |
474
505
  | `docs.routing.default_area` | 初始脚手架子路由 basename。 |
475
506
  | `docs.routing.max_delegation_depth` | 当前最大路由委托深度。 |
507
+ | `truthmark-portal` | 可选手动展示工作流设置:`enabled`、`output` 和 `template`。 |
476
508
  | `authority` | 用作仓库事实权威的有序规范文档和 glob。 |
477
509
  | `instruction_targets` | 接收共享受管说明块的文件,例如 `AGENTS.md`。 |
478
510
  | `frontmatter.required` | 缺失时产生错误诊断的元数据字段。 |
@@ -634,6 +666,21 @@ truthmark impact --base main
634
666
  truthmark context --workflow truth-sync --base main --format markdown
635
667
  ```
636
668
 
669
+ ### 启用可选 Portal 工作流
670
+
671
+ ```yaml
672
+ truthmark-portal:
673
+ enabled: true
674
+ output: docs/truthmark-portal
675
+ template: default
676
+ ```
677
+
678
+ ```bash
679
+ truthmark init
680
+ ```
681
+
682
+ 当你想生成或刷新静态展示站点时,再明确要求代理宿主运行已安装的 Portal 工作流。
683
+
637
684
  ## 项目状态
638
685
 
639
686
  Truthmark V1 目前提供:
@@ -652,6 +699,7 @@ Truthmark V1 目前提供:
652
699
  - 生成的 Truth Preview 工作流表面
653
700
  - 生成的 Truth Realize 工作流表面
654
701
  - 生成的 Truth Check 工作流表面
702
+ - 可选生成的 Truthmark Portal 工作流表面
655
703
  - 路由、权限边界、决策结构、frontmatter、链接、freshness、生成表面和覆盖率诊断
656
704
  - 派生的 RepoIndex、RouteMap、ImpactSet 和 ContextPack 产物
657
705
  - 面向 Codex、Claude Code、GitHub Copilot、OpenCode 和 Gemini CLI 的宿主专属表面
@@ -714,7 +762,7 @@ Truthmark 有意保持小而清晰。
714
762
  - 托管服务
715
763
  - MCP 服务器
716
764
  - 向量数据库
717
- - 文档网站生成器
765
+ - 规范文档网站生成器或托管文档平台
718
766
  - CI 或 PR 强制执行产品
719
767
  - 测试、代码审查或技术领导力的替代品
720
768
  - 自主代码重写引擎