From 1387744d78627c1c9ad392586a2b0d7aa258f81c Mon Sep 17 00:00:00 2001 From: PythonWoods Date: Tue, 21 Apr 2026 19:04:20 +0200 Subject: [PATCH 1/6] =?UTF-8?q?feat:=20Direttiva=20062=20=E2=80=94=20Obsid?= =?UTF-8?q?ian=20Portal=20Reconstruction?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - EngineeringLedger: 3 invariant blocks (Zero Assumptions, Subprocess-Free, Deterministic Dependency Graph) replacing the Features grid; extracted from /website Astro foundry standards. macOS-style terminal boxes, two-column layout. - Quickstart: Paperclip-pattern anchor #quickstart at bottom — terminal box with 'uvx zenzic lab' + 'uvx zenzic check all .'; Star on GitHub + Read the docs CTAs. - Hero: 'Get Started' → smooth-scroll anchor (Link removed). - homepage.css: scroll-behavior: smooth under .zz-homepage scope. - i18n: EN + IT keys for ledger.* (10) and quickstart.* (5). Build: clean EN + IT. --- i18n/en/code.json | 45 +++++ i18n/it/code.json | 45 +++++ src/components/Homepage/EngineeringLedger.tsx | 175 ++++++++++++++++++ src/components/Homepage/Hero.tsx | 9 +- src/components/Homepage/Quickstart.tsx | 100 ++++++++++ src/css/homepage.css | 5 + src/pages/index.tsx | 6 +- 7 files changed, 379 insertions(+), 6 deletions(-) create mode 100644 src/components/Homepage/EngineeringLedger.tsx create mode 100644 src/components/Homepage/Quickstart.tsx diff --git a/i18n/en/code.json b/i18n/en/code.json index dd73e23..38cb955 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -211,6 +211,51 @@ "sentinel.summary.failed": { "message": "FAILED: One or more checks failed." }, + "ledger.label": { + "message": "The Obsidian Engineering Ledger" + }, + "ledger.heading": { + "message": "Three invariants enforced on every commit." + }, + "ledger.heading.muted": { + "message": "No exceptions. No shortcuts." + }, + "ledger.sub": { + "message": "These are not aspirations \u2014 they are gates. Every release of Zenzic ships only when all three pass." + }, + "ledger.01.title": { + "message": "Zero Assumptions at System Boundaries" + }, + "ledger.01.desc": { + "message": "Every public entry point validates its inputs at the boundary. Internal hot paths carry no defensive checks \u2014 the shape is guaranteed by the type system, enforced by mypy --strict on every merge." + }, + "ledger.02.title": { + "message": "Subprocess-Free Analysis" + }, + "ledger.02.desc": { + "message": "Production-grade tools do not shell out during analysis. No subprocess.run(), no os.system() inside per-item loops. Zenzic validates your documentation stack without executing it." + }, + "ledger.03.title": { + "message": "Deterministic Dependency Graph" + }, + "ledger.03.desc": { + "message": "Every dependency is pinned in a lockfile, audited by Dependabot, and scanned for SPDX licence compatibility. No transitive surprises at release time. uv lock and reuse lint run on every commit." + }, + "quickstart.label": { + "message": "Get Started" + }, + "quickstart.heading": { + "message": "From zero to documentation integrity in one command." + }, + "quickstart.sub": { + "message": "No configuration required. No account needed. Works on any Markdown project." + }, + "quickstart.github": { + "message": "Star on GitHub" + }, + "quickstart.docs": { + "message": "Read the full docs \u2192" + }, "theme.ErrorPageContent.title": { "message": "This page crashed.", "description": "The title of the fallback page when the page crashed" diff --git a/i18n/it/code.json b/i18n/it/code.json index 39dc999..eb1dcf1 100644 --- a/i18n/it/code.json +++ b/i18n/it/code.json @@ -792,5 +792,50 @@ }, "sentinel.summary.failed": { "message": "FAILED: One or more checks failed." + }, + "ledger.label": { + "message": "L\u2019Obsidian Engineering Ledger" + }, + "ledger.heading": { + "message": "Tre invarianti verificati ad ogni commit." + }, + "ledger.heading.muted": { + "message": "Nessuna eccezione. Nessuna scorciatoia." + }, + "ledger.sub": { + "message": "Non sono aspirazioni \u2014 sono requisiti. Zenzic viene rilasciato solo quando tutti e tre passano." + }, + "ledger.01.title": { + "message": "Zero Assunzioni ai Confini del Sistema" + }, + "ledger.01.desc": { + "message": "Ogni entry point pubblico valida i propri input al confine. I percorsi interni non contengono controlli difensivi \u2014 la forma \u00e8 garantita dal sistema di tipi, imposta da mypy --strict ad ogni merge." + }, + "ledger.02.title": { + "message": "Analisi Senza Sottoprocessi" + }, + "ledger.02.desc": { + "message": "Gli strumenti di livello produzione non eseguono shell durante l\u2019analisi. Nessun subprocess.run(), nessun os.system() nei loop per-item. Zenzic valida il tuo stack documentale senza eseguirlo." + }, + "ledger.03.title": { + "message": "Grafo delle Dipendenze Deterministico" + }, + "ledger.03.desc": { + "message": "Ogni dipendenza \u00e8 bloccata in un lockfile, verificata da Dependabot e analizzata per compatibilit\u00e0 SPDX. Nessuna sorpresa transitiva al momento del rilascio. uv lock e reuse lint vengono eseguiti ad ogni commit." + }, + "quickstart.label": { + "message": "Inizia" + }, + "quickstart.heading": { + "message": "Da zero all\u2019integrit\u00e0 documentale in un solo comando." + }, + "quickstart.sub": { + "message": "Nessuna configurazione richiesta. Nessun account necessario. Funziona su qualsiasi progetto Markdown." + }, + "quickstart.github": { + "message": "Star su GitHub" + }, + "quickstart.docs": { + "message": "Leggi la documentazione completa \u2192" } } diff --git a/src/components/Homepage/EngineeringLedger.tsx b/src/components/Homepage/EngineeringLedger.tsx new file mode 100644 index 0000000..45681b3 --- /dev/null +++ b/src/components/Homepage/EngineeringLedger.tsx @@ -0,0 +1,175 @@ +// SPDX-FileCopyrightText: 2026 PythonWoods +// SPDX-License-Identifier: Apache-2.0 +import React from 'react'; +import Translate from '@docusaurus/Translate'; + +// ── Minimal terminal box ─────────────────────────────────────────────────── +function LedgerTerminal({ + filename, + children, +}: { + filename: string; + children: React.ReactNode; +}): React.JSX.Element { + return ( +
+
+
+
+ {children} +
+
+ ); +} + +// ── One ledger row ───────────────────────────────────────────────────────── +function LedgerRow({ + index, + title, + desc, + terminal, +}: { + index: string; + title: React.ReactNode; + desc: React.ReactNode; + terminal: React.ReactNode; +}): React.JSX.Element { + return ( +
+
+ + {index} + +

+ {title} +

+

{desc}

+
+
{terminal}
+
+ ); +} + +// ── The Obsidian Engineering Ledger ─────────────────────────────────────── +export default function EngineeringLedger(): React.JSX.Element { + return ( +
+
+ {/* Section header */} +
+

+ The Obsidian Engineering Ledger +

+

+ Three invariants enforced on every commit.{' '} + + No exceptions. No shortcuts. + +

+

+ + These are not aspirations — they are gates. Every release of Zenzic ships only when + all three pass. + +

+
+ + {/* ── 01 — Zero Assumptions ─────────────────────────────────────── */} + Zero Assumptions at System Boundaries + } + desc={ + + Every public entry point validates its inputs at the boundary. Internal hot paths + carry no defensive checks — the shape is guaranteed by the type system, enforced by + mypy --strict on every merge. + + } + terminal={ + + 
+                
+                  {`[tool.mypy]
+strict            = true
+warn_return_any   = true
+warn_unreachable  = true
+
+# Every public function has a typed signature.
+# Every Any must be justified in a comment.`}
+                
+
+ + } + /> + + {/* ── 02 — Subprocess-Free ──────────────────────────────────────── */} + Subprocess-Free Analysis} + desc={ + + Production-grade tools do not shell out during analysis. No subprocess.run(), no + os.system() inside per-item loops. Zenzic validates your documentation stack without + executing it. + + } + terminal={ + + 
+                
+                  {`# ✓ ALLOWED — single setup phase
+class ZenzicEngine:
+    def __init__(self, config: Config):
+        self._vsm = build_vsm(config)   # I/O once
+
+# ✗ BLOCKED — subprocess inside analysis loop
+for page in corpus:
+    subprocess.run([...])  # ← architectural defect`}
+                
+
+ + } + /> + + {/* ── 03 — Deterministic Dependency Graph ───────────────────────── */} + Deterministic Dependency Graph + } + desc={ + + Every dependency is pinned in a lockfile, audited by Dependabot, and scanned for + SPDX licence compatibility. No transitive surprises at release time. uv lock and + reuse lint run on every commit. + + } + terminal={ + + 
+                
+                  {`# runs on every commit via pre-commit
+nox -s reuse
+
+✓ SPDX headers present   │ all source files
+✓ Apache-2.0 declared    │ LICENSES/
+✓ Third-party notices    │ NOTICE
+# No dependency ships
+# without a licence audit.`}
+                
+
+ + } + /> +
+
+ ); +} diff --git a/src/components/Homepage/Hero.tsx b/src/components/Homepage/Hero.tsx index 787e92f..728d420 100644 --- a/src/components/Homepage/Hero.tsx +++ b/src/components/Homepage/Hero.tsx @@ -1,5 +1,4 @@ import React from 'react'; -import Link from '@docusaurus/Link'; import useBaseUrl from '@docusaurus/useBaseUrl'; import Translate, { translate } from '@docusaurus/Translate'; @@ -13,7 +12,6 @@ export function SentinelBadge(): React.JSX.Element { } export default function Hero(): React.JSX.Element { - const docsHref = useBaseUrl('/docs/'); const iconUrl = useBaseUrl('/assets/brand/svg/zenzic-icon.svg'); return ( @@ -44,11 +42,14 @@ export default function Hero(): React.JSX.Element {

- + Get started - + View on GitHub diff --git a/src/components/Homepage/Quickstart.tsx b/src/components/Homepage/Quickstart.tsx new file mode 100644 index 0000000..ec141cb --- /dev/null +++ b/src/components/Homepage/Quickstart.tsx @@ -0,0 +1,100 @@ +// SPDX-FileCopyrightText: 2026 PythonWoods +// SPDX-License-Identifier: Apache-2.0 +import React from 'react'; +import Link from '@docusaurus/Link'; +import useBaseUrl from '@docusaurus/useBaseUrl'; +import Translate from '@docusaurus/Translate'; + +export default function Quickstart(): React.JSX.Element { + const docsHref = useBaseUrl('/docs/'); + + return ( +
+
+ {/* Label */} +

+ Get Started +

+ + {/* Heading — mirrors Paperclip "From zero to autonomous company in one command." */} +

+ + From zero to documentation integrity in one command. + +

+

+ + No configuration required. No account needed. Works on any Markdown project. + +

+ + {/* Terminal box */} +
+ {/* macOS window chrome */} +
+
+ + {/* Commands */} +
+

+ # explore the interactive lab (9 acts, zero setup) +

+
+ + $ + + uvx zenzic lab +
+

+ # audit your documentation right now +

+
+ + $ + + uvx zenzic check all . +
+
+
+ + {/* Action buttons */} +
+ + {/* GitHub icon */} + + Star on GitHub + + + + Read the full docs → + +
+
+
+ ); +} diff --git a/src/css/homepage.css b/src/css/homepage.css index 5eed141..2d7b550 100644 --- a/src/css/homepage.css +++ b/src/css/homepage.css @@ -25,3 +25,8 @@ .zz-homepage a:hover { text-decoration: none; } + +/* Smooth scroll for the #quickstart anchor */ +.zz-homepage { + scroll-behavior: smooth; +} diff --git a/src/pages/index.tsx b/src/pages/index.tsx index f22731c..bad230b 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -4,9 +4,10 @@ import Layout from '@theme/Layout'; import '@site/src/css/homepage.css'; import Hero from '../components/Homepage/Hero'; -import Features from '../components/Homepage/Features'; +import EngineeringLedger from '../components/Homepage/EngineeringLedger'; import SentinelSection from '../components/Homepage/SentinelSection'; import QualityScore from '../components/Homepage/QualityScore'; +import Quickstart from '../components/Homepage/Quickstart'; export default function Home(): React.JSX.Element { return ( @@ -24,9 +25,10 @@ export default function Home(): React.JSX.Element {
- + +