From 48a4e357f228f215bfb21e32ad35b0bb3534b6cb Mon Sep 17 00:00:00 2001 From: ZDDC Date: Thu, 11 Jun 2026 12:03:59 -0500 Subject: [PATCH] docs: simplify to three local-first tools (actual content) Follow-up to c3ba81a, which deleted federal.html but missed the file edits (the prior git add aborted on a pathspec error). This commit carries the real changes: remove the zddc-server + install sections and all server discussion from the landing page; lead with "runs in your browser, files never leave your machine, start with Browse now"; give each tool card a bulleted feature list; lay the three cards out all-across or all-stacked via a shared .tools-grid. In the reference, remove Section 10 (server bootstrap), renumber Tools to 10, and de-couple Section 9's layout/workflow from server machinery. Co-Authored-By: Claude Opus 4.8 (1M context) --- css/style.css | 13 +++ index.html | 137 ++++++++------------------- reference.html | 250 +++++++------------------------------------------ 3 files changed, 86 insertions(+), 314 deletions(-) diff --git a/css/style.css b/css/style.css index 12cf773..df3a136 100644 --- a/css/style.css +++ b/css/style.css @@ -514,6 +514,19 @@ html[data-theme="dark"] .filename-parts__dot--status { background: var(--color-accent-hover); } +/* Three tool cards: all three side by side on wide screens, all three + stacked on narrow screens — never a 2-then-1 wrap. */ +.tools-grid { + display: grid; + grid-template-columns: 1fr; + gap: var(--spacing-lg); + margin-top: var(--spacing-lg); + align-items: start; +} +@media (min-width: 860px) { + .tools-grid { grid-template-columns: repeat(3, 1fr); } +} + /* ── Steps List ── */ .steps { margin: var(--spacing-xl) 0; diff --git a/index.html b/index.html index e868223..3993570 100644 --- a/index.html +++ b/index.html @@ -15,23 +15,11 @@ @@ -84,7 +72,8 @@

Zero Day Document Control

-

A file-naming convention plus a few single-file HTML tools for managing project deliverables. Start with Browse — open any folder, no setup. Self-contained, offline-capable, dependency-free.

+

Three small tools for managing project deliverables, plus a simple file-naming convention. Each tool is one HTML file that runs entirely in your browser — open it, point it at a folder on your computer, and go. Nothing to install, no account, no server. Your files never leave your machine.

+

Open Browse now →

@@ -92,117 +81,65 @@

What is it?

-

ZDDC is a convention, not a platform. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain shared folder becomes a fully searchable, auditable information-management system — no server, no database, no software required to read the archive.

-

The tools below are optional interfaces around this structure, and each needs nothing to run. Every one is a single self-contained HTML file: open it and point it at a folder on your disk, or put it behind any web server (including the optional zddc-server described below) and use it over the network. Same on-disk layout either way. The extra niceties — friendly labels, per-folder tools, permissions — come from optional .zddc files you can add later, or never.

+

ZDDC is a convention, not a platform. Every deliverable's filename encodes its tracking number, revision, status, and title; every transmittal folder is date-prefixed and self-describing. A plain folder on your computer or a shared drive becomes a fully searchable, auditable record — no server, no database, no software required to read it.

+

The three tools below are optional helpers around this structure. Each is a single HTML file that works entirely on your own machine: open it, pick a folder, and you're working. They run offline and never upload anything. You can start with Browse on your existing files right now — there's nothing to set up first.

Read the full specification →

-

Try the tools

-

Each tool is a single self-contained HTML file. The link below always tracks the current stable; pin to a specific version on the releases page for reproducibility.

+

The tools

+

Three single-file apps. Click one to open it now, or right-click → Save As to keep your own copy — each works offline forever, with no install and no updates.

-
+
Start here
Browse
-
Open any folder on your disk — that's the whole setup. A file-tree navigator with live preview for the things you actually have: PDFs, Office docs, images, markdown. Edit markdown in place and download it as DOCX, HTML, or PDF on demand. Add optional .zddc files and the same tool gains friendly folder labels, per-folder tools, permissions, and transmittal actions — leave them out and it's still a complete browser.
-
Open Browse →
+
Look at any folder — no setup at all.
+
    +
  • Open files on your computer and preview them instantly — PDFs, Word, Excel, images, markdown
    • +
  • Move through your folders the way you already think about them
    • +
  • Edit markdown in place and save it as Word, PDF, or HTML
    • +
  • Works completely offline; your files stay on your machine
    • +
+
Open Browse →
Classify
-
Turn a pile of incoming files into properly named ZDDC deliverables. Drop files onto a tree to assign each one a tracking number, revision, and status, then organize them into dated transmittal folders ready to issue. Spreadsheet-style editing; writes the renamed, sorted copies straight back to disk. No server needed.
-
Open Classify →
+
Name and sort a pile of incoming files.
+
    +
  • Rename messy files into clean, consistent names
    • +
  • Give each file a tracking number, revision, and status just by dropping it into place
    • +
  • Group deliverables into dated transmittal folders, ready to send
    • +
  • Edit like a spreadsheet; saves the organized copies back to your folder
    • +
+
Open Classify →
Archive
-
The read-only window into the formal record. Filter by tracking number, discipline, revision, status, or free text; group rows by transmittal to see each deliverable's lifecycle; export the current selection as a ZIP. The archive is preserved exactly as-issued.
-
Open Archive →
+
Find anything in your record.
+
    +
  • Search and filter by tracking number, status, discipline, or plain text
    • +
  • See every revision of a deliverable and where it is in its lifecycle
    • +
  • Group by transmittal to see what was sent, and when
    • +
  • Download any selection as a ZIP — read-only, nothing gets changed
    • +
+
Open Archive →
-

Append ?v=v0.0.4 to any URL to load a specific version for a single request — useful for sharing a link to an exact build. Direct local-folder access requires a Chromium-based browser (the File System Access API is unavailable in Firefox / Safari). Browse all versions →

-
- - -
-

zddc-server (optional)

-

The tools work two ways over the same on-disk archive. Pick whichever fits your team:

- -
-
-

Local directory mode

-

Open a tool, click Add Directory, point it at a folder. The tool reads files via the File System Access API. No upload, no server, no account.

-

Enough for individual users and small teams on a shared drive (network share, Dropbox, OneDrive, syncthing).

-
-
-

Online mode

-

Take the same local directory and put it behind any web server (nginx, Caddy, Apache, or zddc-server). The Archive tool talks to the server's directory listings instead of the local filesystem — read-only, works in any browser.

-
-
- -

zddc-server is an optional web-server app, purpose-built to serve a ZDDC archive over the network. Any web server gives you read-only online mode; zddc-server adds the things a generic one can't:

- -
    -
  • Access control, no database. Drop optional .zddc files along the tree to say who can read, write, create, or delete each folder — by email, wildcard, or named role. Write-once (WORM) archive folders keep the issued record immutable. How the cascade works →
    • -
  • Less to set up. The canonical project layout appears on first use, the tools are baked in and served at the right paths automatically, and a virtual .archive URL always resolves to the current revision of any document.
    • -
  • Built for regulated environments. Hardened TLS, per-request audit logging, and a pluggable policy engine (swap in Open Policy Agent with your own Rego). See the federal compliance page for the supported deployment shape.
    • -
- -

The on-disk layout is the same in both modes. Stop the server and the directory is still a perfectly valid ZDDC archive that opens in local-directory mode. The server is convenience, not lock-in.

- -

Source, configuration, and the full ACL reference: codeberg.org/VARASYS/ZDDC zddc/.

-
- -
-

Install on your server

-

Two paths, no install scripts. The server has built-in fetch-and-cache for the tool HTMLs; the local-file path needs nothing more than a download.

- -
-
-

Server: just run zddc-server

-

The app has the current-stable build of the tools baked in. They appear automatically at the right paths in the served tree:

-
    -
  • browse.html at every directory (the slash form of any path) — the file-tree navigator, in-place markdown editor, and inbound-file handling surface
    • -
  • archive.html at every archive/ path — the read-only search-and-export view of the formal record
    • -
  • classifier.html wherever a folder opts into it — assign tracking numbers and build transmittals
    • -
  • index.html (the project picker) at the deployment root
    • -
-

Which tool serves at a given URL is decided by the .zddc cascade — the embedded defaults map archive/ subtrees to the archive tool and everything else to browse, but operators can override per folder via default_tool:. Folder names are case-insensitive — Working/, working/, and WORKING/ all match the same rule.

-
./zddc-server
-

No flags needed for a quick start. The served tree defaults to the current working directory; the listener defaults to https://localhost:8443/ with a self-signed certificate. --root, --addr, and --tls-cert / --tls-key override each. --help prints the full flag list.

-

To override a tool at any path: drop a real .html file there — that file wins over the baked-in version. To pin a different version, write an apps: entry in any .zddc file along the path:

-
# <project>/.zddc
-apps:
-  browse: stable         # latest stable, or v0.0.4 to pin an exact version
-  archive: https://my-fork.example/archive.html
-

URL sources are fetched once and cached in <ZDDC_ROOT>/_app/. To force a re-fetch, delete the cache file. Closer-to-leaf .zddc entries override parent ones.

-
- -
-

Local: just download the .html file

-

No server, no install — open in any modern browser.

- -

Right-click → Save As. Each tool is a self-contained HTML file with everything inlined; works from file:// or any static host.

-
-
+

To open a folder straight from your computer, use a Chromium-based browser — Chrome, Edge, or Brave. That one feature isn't available in Firefox or Safari yet. Browse all versions →

Learn more

    -
  • Technical Reference — the full ZDDC convention: filename format, tracking numbers, revisions, status codes, folder naming, transmittal workflow.
    • -
  • Access control reference — cascade rules, common deployment shapes (paired open/closed projects + third-party-vendor folders), anti-patterns, a five-minute verify-it-works recipe, the federal-readiness gap analysis with NIST control references, and the OPA-compatible decider configuration.
    • -
  • For federal evaluators — non-technical walk-through of what's already in place, the supported deployment shape, what an integrator adds during ATO, and the two-track build plan. Procurement-friendly entry point that links back to engineering detail.
    • -
  • All releases — every version of every tool, with per-version pin URLs.
    • -
  • codeberg.org/VARASYS/ZDDC — source code, issue tracker, contributor docs.
    • +
  • Technical Reference — the full ZDDC convention: filename format, tracking numbers, revisions, status codes, folder naming, and transmittal workflow.
    • +
  • All releases — every version of every tool.
    • +
  • codeberg.org/VARASYS/ZDDC — source code and issue tracker.
diff --git a/reference.html b/reference.html index 45c9471..ebe47a0 100644 --- a/reference.html +++ b/reference.html @@ -84,8 +84,7 @@
7. Status codes
8. Folder naming
9. Transmittal workflow
-
10. zddc-server bootstrap
-
11. Tools
+
10. Tools
@@ -223,10 +222,10 @@ status = "IFA" / "IFB" / "IFC" / "IFD" / "IFI" / "IFP" / "IFR" / "IFU" / "
-

zddc-server defaults. The schemas above are deployment-agnostic — any of them is a valid tracking number. The zddc-server reference implementation ships the Basic schema by default (originator-project-discipline-type-sequence), plus the optional per-deliverable [suffix] (a hyphenated part marker such as -A for an appendix). Two deployment behaviours are worth knowing:

+

A sensible default profile. The schemas above are all valid tracking numbers; pick the one that fits your project. A common starting point is the Basic schema (originator-project-discipline-type-sequence), plus the optional per-deliverable [suffix] (a hyphenated part marker such as -A for an appendix). Two conventions are worth knowing:

    -
  • originator is bound to the party folder. Under archive/<party>/, the server sets originator from the party-folder name and renders it read-only — the folder is its single source of truth, so it can't drift from where the deliverable is filed.
    • -
  • phase and area are off by default. Because they are project-wide (all-or-nothing across a project), the default omits them; a project that needs them enables them on every deliverable by extending the schema in its .zddc configuration.
    • +
  • originator follows the party folder. When deliverables are filed under a per-party folder, the originator matches that folder's name — the folder is the single source of truth, so the code can't drift from where the document is filed.
    • +
  • phase and area are off by default. Because they are project-wide (all-or-nothing across a project), most projects omit them; a project that needs them adds them to every deliverable.
@@ -1013,75 +1012,33 @@ date = 4DIGIT "-" 2DIGIT "-" 2DIGIT

9. Project layout & transmittal workflow

-

A ZDDC project mirrors the natural lifecycle of an engineering deliverable: drafted in private, lined up for issue, formally exchanged, kept as record. Each canonical folder maps to one of those stages, so file location alone tells you where a document is in its lifecycle. An operator only needs to create one file — a .zddc in an empty directory — and the rest of the layout populates as work happens.

+

A ZDDC project mirrors the natural lifecycle of an engineering deliverable: drafted in private, lined up for issue, formally exchanged, kept as record. Each folder maps to one of those stages, so file location alone tells you where a document is in its lifecycle. You only create the folders you need, when you need them.

project/ - .zddc ← the only file an operator must create - - archive/ ← The only PHYSICAL project-root directory. - Everything party-scoped (records, lifecycle, - immutable archives) lives uniformly under - archive/<party>/. - {party-name}/ ← One per counterparty; one for ourselves. - We treat our own organisation as just another - party so internal deliverables get the same - tracking treatment as external ones. - mdl/ ← The party's Master Deliverables List — - what they're going to produce. Opens as - a grid editor; rows are individual .yaml - files, one per deliverable. - rsk/ ← Risk register for this party. Same grid - editor as mdl/. - incoming/ ← Where the counterparty drops things for us. - A quality-check buffer before content - becomes part of the permanent record. - received/ ← What we've accepted from that party. - Immutable (WORM); the historical record - of inbound documents. - issued/ ← What we sent to that party. Immutable - (WORM); the historical record of outbound - documents. - working/ ← Where this party's staff draft. Each - person has a private subfolder here - (named by email) and iterates until ready - to commit. The browse tool handles - everything here. - <your-email>/ ← Your private workspace under THIS - party. Fenced (inherit:false) by the - auto-own .zddc, so other team members - only see what you explicitly share. - staging/ ← The "about to issue" lane for this party. - Drop files here and the project_team - gives them up — only the doc-controller - can change a file after it lands. Each - sub-folder declares a planned outbound - transmittal (name carries the date + - tracking number). - reviewing/ ← One place per party to see everything we - owe a response on. Folders are scaffolded - by Plan Review, each pairing an inbound - submittal in received/ with the in-progress - response draft. - - ssr/ ← Virtual aggregator: tables rollup of every - party's ssr.yaml row, with a synthesised - $party column. Never on disk. - mdl/ ← Virtual aggregator: tables rollup of every - party's mdl/*.yaml deliverables. - rsk/ ← Virtual aggregator: tables rollup of every - party's rsk/*.yaml risk rows. - working/ ← Virtual aggregator: browse folder-nav listing - parties with non-empty content in working/. - Per-party clicks 302-redirect to the canonical - archive/<party>/working/. - staging/ ← Same shape as working/ for the staging slot. - reviewing/ ← Same shape as working/ for the reviewing slot. + archive/ ← Holds everything, organised by party. + {party-name}/ ← One folder per organisation you exchange + with — and one for yourselves. Your own + deliverables get the same treatment as + anyone else's. + mdl/ ← Master Deliverables List for this party — + what they are going to produce. + rsk/ ← Risk register for this party. + incoming/ ← Where this party drops things for you; + a checking buffer before you accept them. + received/ ← What you have accepted from that party. + A permanent, write-once record. + issued/ ← What you have sent to that party. + A permanent, write-once record. + working/ ← Where your team drafts. Each person works + in their own subfolder until a file is ready. + staging/ ← The "about to issue" lane: drop finished + files here to line up an outbound transmittal. + reviewing/ ← One place to track everything you owe a + response on.
-

Mechanics: folders materialise on first write, names match case-insensitively, the WORM zones (received/, issued/) enforce write-once via an ACL mask, and the six top-level aggregators (ssr/mdl/rsk/working/staging/reviewing) are virtual — they never materialise on disk but show up in listings, computed from archive/<party>/… at request time. Mkdir at the project root is restricted to archive + system names (_/.-prefixed) so the virtual names can never be shadowed by a physical folder. Drop files where the lifecycle says they go and the layout takes care of itself.

- -

The in-flight ratchet. working/ → staging/ → issued/ is a one-way handoff. project_team iterates freely in working/ (the auto-own-fenced subfolder gives each user a private rwcda workspace). When they drop a file into staging/ their access downgrades to cr — they can drop more, but only the document_controller can change what's already there. When DC publishes to issued/, the WORM mask downgrades even DC to cr (write-once). Each handoff is a commitment by permission-loss.

+

How it flows. working/ → staging/ → issued/ is a one-way progression: your team drafts freely in working/, lines finished files up in staging/ for the document controller to sign off, and the document controller publishes the package into issued/ as the permanent record. Treat received/ and issued/ as write-once — once a document lands there, it stays exactly as filed.

5-step transmittal workflow:

@@ -1133,156 +1090,21 @@ project/

Drafting a response transmittal

-

Submittals from counterparties (tracking numbers containing -SUB- at status IFR or IFA) require a response transmittal whose status starts with RS (RSA, RSB, RSC, …). The flow walks the ratchet:

+

Submittals from counterparties (tracking numbers containing -SUB- at status IFR or IFA) require a response transmittal whose status starts with RS (RSA, RSB, RSC, …). The flow follows the same lifecycle:

    -
  1. Right-click the submittal in archive/<party>/received/<tracking>/ and pick Plan Review. The server scaffolds a workflow folder at archive/<party>/reviewing/<tracking>/ — its .zddc carries a received_path pointer back to the canonical submittal and a planned response date.
    2. -
  2. The party's working subfolder under archive/<party>/working/<your-email>/ is where reviewer notes and the response payload are drafted. The reviewing/ virtual aggregator at the project root surfaces all open reviews across parties.
    3. -
  3. When the response is ready, files move from working/ into archive/<party>/staging/ for sign-off. Project team's permission on staged files downgrades to cr — the doc controller takes over.
    4. -
  4. The doc controller cuts the package from staging/ into archive/<party>/issued/ via the standard 5-step transmittal flow. The reviewing scaffold is deleted at issue time.
    5. +
  5. For a submittal in received/, start a review folder under reviewing/ that points back to it, so every open response is in one place.
    6. +
  6. Draft your reviewer notes and the response itself in working/.
    7. +
  7. When the response is ready, move the files into staging/ for the document controller to sign off.
    8. +
  8. The document controller issues the package from staging/ into issued/ via the standard 5-step transmittal flow.
- -
-

10. zddc-server bootstrap

- -
-

A fresh zddc-server deployment grants no access to anyone until two config files are populated. Without them the server runs but every request returns 403. The embedded defaults ship with empty role members, so deployments must opt-in to authorize anyone — there is no default "anything goes" mode (except --insecure, which is explicitly for deliberately-public archives).

-
- -

Two files, both named .zddc. YAML format. Hand-edited.

- -

Step 1 — root /.zddc

- -

At <ZDDC_ROOT>/.zddc, name at least one admin:

- -
admins: - - cwitt@burnsmcd.com -
- -

admins: is honored only at the root file. Admins behave as normal users by default and elevate per-request via the zddc-elevate=1 cookie (the header toggle visible in every tool) or implicitly when authenticating with a bearer token. This sudo-style model means an admin can't accidentally clobber files in their everyday browsing — elevation is opt-in.

- -

Without this file the server refuses to start (the served tree would be publicly accessible to anonymous callers); pass --insecure to acknowledge a deliberately-public deployment.

- -

Step 2 — per-project <project>/.zddc

- -

In each project, populate role members:

- -
title: "Project Phoenix" -roles: - document_controller: - members: - - dc1@burnsmcd.com - project_team: - members: - - '*@burnsmcd.com' # all internal staff - observer: # optional — external audit - members: - - auditor@external.com -
- -

That's it. The embedded cascade does the rest:

- -
    -
  • project_team gets read across the project plus the in-flight ratchet (cr in working/ + reviewing/ + staging/, with rwcda inside each user's auto-own-fenced home under working/).
    • -
  • document_controller creates party folders at archive/; when they do, the auto-own .zddc written at archive/<party>/ grants both their email AND the document_controller role rwcda — so any DC in the role has full authority at every party a peer created. Explicit rwcd grants at incoming//staging/ for the QC + transfer workflows, and WORM cr at received//issued/ for write-once filing.
    • -
  • observer is pure read-only across the project — intended for external auditors, regulators, and read-only viewers who must not contribute content.
    • -
- -

A DC is typically also a project team member (the *@burnsmcd.com glob catches them). The embedded defaults restate document_controller: rwcda at every slot that grants project_team a narrower verb — within-level union of all matched principals gives DCs rwcda ∪ cr = rwcda, preserving full authority. Document controllers are not subtree-admins anywhere. Their power comes purely from cascade grants; admin elevation is reserved for the root admins: list (the human escape hatch).

- -

Add a new project team member with one line; revoke by removing the line. No need to restate the cascade's grants — they're already in the embedded defaults that ship with zddc-server.

- -

Schema essentials

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyWhereShape
admins:Root onlyList of emails. Sudo-style; gates on zddc-elevate=1.
acl:Anywhere; cascades{ permissions: { <principal>: <bits> }, inherit: <bool>? }
roles:Anywhere; members union across the cascade{ <name>: { members: [...], reset: <bool>? } }
title:Per-project onlyString; surfaces on the landing-page picker.
- -

Permission bits — any subset of:

- -
    -
  • r read
    • -
  • w write (overwrite existing files)
    • -
  • c create (new files, new directories)
    • -
  • d delete
    • -
  • a admin (modify the .zddc ACL at this level — distinct from the root admins: list, which is the elevation-bypass sudo channel)
    • -
- -

An empty bits string ('') is an explicit deny.

- -

Principals — three forms:

- -
    -
  • Email address — must contain @, e.g. alice@burnsmcd.com
    • -
  • Email glob — wildcard on the local part, e.g. '*@acme.com' (quote it in YAML so the leading * doesn't confuse the parser)
    • -
  • Role name — anything without an @, e.g. document_controller. The role's members are looked up via roles: at any cascade level.
    • -
- -

Common footgun

- -
-

This is silently dropped:

-
acl: - allow: - - '*@burnsmcd.com' -
-

The YAML parses cleanly but ACLRules only reads permissions:. The allow: block is discarded during unmarshal and you end up with zero grants. Correct form:

-
acl: - permissions: - '*@burnsmcd.com': r -
-
- -

Verifying the bootstrap

- -

zddc-server prints a startup warning when the root .zddc grants nobody anything — watch for it on first boot:

- -
level=WARN msg="root .zddc grants nobody anything (no admins, -no acl.permissions, no role members). ZDDC will refuse every -request until you populate it..."
- -

To dump the full annotated schema (every cascade key with documentation):

- -
zddc-server show-defaults
- -

That prints the embedded defaults.zddc.yaml with comments explaining every option (worm:, auto_own:, auto_own_roles:, auto_own_fenced:, drop_target:, apps:, convert:, records:, available_tools:, default_tool:, dir_tool:, and more). Pipe it to a file and use it as the starting point for any deeper customization.

-
- - +
-

11. Tools

-

Single-file HTML applications — each is complete and self-contained. Save one locally and it works forever, without internet, without updates, without a subscription. None of them require any configuration to run; .zddc files and zddc-server only add to them. Together they cover the full ZDDC workflow: browse to look at anything; classify to name incoming files and build transmittals; archive to search and export the formal record.

+

10. Tools

+

Single-file HTML applications — each is complete and self-contained. Save one locally and it works forever, without internet, without updates, without a subscription. None of them require any configuration to run; optional .zddc files only add to them. Together they cover the full ZDDC workflow: browse to look at anything; classify to name incoming files and build transmittals; archive to search and export the formal record.

-
+
Browse
Open any folder on your disk — no setup. A file-tree navigator with live preview, plus in-place markdown editing (YAML front matter pane, table of contents) and export to DOCX, HTML, or PDF. Optional .zddc files add friendly labels, per-folder tools, permissions, and transmittal actions; without them it is still a complete browser.
@@ -1302,7 +1124,7 @@ request until you populate it..."
-

Local directory access relies on the Chromium-based browser File System Access API. It does not work in Firefox or Safari. Run the tools through zddc-server for any browser, network access, and ACL enforcement.

+

To open a folder directly from your computer, use a Chromium-based browser — Chrome, Edge, or Brave. That feature relies on the browser's File System Access API, which Firefox and Safari do not yet support.