01 — Policy Rules
These 10 rules apply to every HTML document in the Nexus docs directory without exception.
P-01No ASCII diagrams. Unicode box-drawing characters (U+2500–U+257F), pipe-and-dash art, preformatted ASCII flow charts, and CSS flex-box pseudo-diagrams with Unicode arrows (→, ←, etc.) are FORBIDDEN. See UV_DIAGRAM_POLICY.md for the complete diagram policy. ONLY WORMWOOD_APP interactive canvas diagrams are permitted.
P-02All HTML docs must have a functioning site-nav. The nav must use the
site-nav / site-nav-inner / site-nav-brand / site-nav-link class pattern from NEXUS_BACKLOG.html. The nav tag alone without the CSS is a violation.P-03No emojis. Never in any HTML file, template, comment, or inline style. This includes Unicode emoji ranges U+1F300–U+1F9FF and common single-char symbols used decoratively.
P-04Status pills must be accurate. Complete means: UI built, backend built, tested, demo-able. Backend Only for API-only work. CLI Only for CLI-only work. Not Started when nothing exists. A claimed status that cannot be demonstrated is a lie and must be corrected.
P-05File naming. Nexus platform docs:
NEXUS_*.html. Use case docs: NEXUS_USECASE_*.html. Old Nexus rule engine docs: NEXUS_*.html or unchanged legacy names. Never name a new doc with the Nexus prefix for Nexus platform content.P-06Product naming. The product is Nexus. The underlying rule engine component is Nexus. The product was formerly known as Nexus before it absorbed Nexus capabilities and took the Nexus name. Every doc must clearly refer to Nexus as the product and Nexus as the rule engine component.
P-07Sanctioned diagram type: WORMWOOD_APP interactive canvas ONLY. The ONLY permitted diagram format is the WORMWOOD_APP interactive canvas (WORMWOOD_APP.html) with SVG flexible connectors rendered by
nexus-core.js. Forbidden — ZERO TOLERANCE: .nxd-flow with .nxd-arrow (flex-box pseudo-diagrams with → Unicode), .flow-diagram, ASCII art, Mermaid, static SVG/PNG. If you cannot use WORMWOOD_APP canvas, use tables or lists instead. See UV_DIAGRAM_POLICY.md for complete enforcement rules.P-08Cross-doc links. Every doc must link back to
index.html via the site-nav brand link. Use case docs must link to the parent product plan. Backlog and action plan must be cross-linked. No orphaned documents.P-09Color tokens. Only
:root CSS variable colors from the active Nexus theme. Never hardcoded hex colors outside of :root. Use-case accent colors: blue (#4F8EF7) for Nesto, purple (#A78BFA) for ENDO, orange (#F28C28) for ARC. These are fixed and must not change between documents.P-10Version tags. Every document must have a version tag or date in the header. When content changes, update the date. Never leave a stale date when making content edits.
P-11No scrollbars on the site navigation bar. The
.site-nav-inner element must use overflow: visible. Using overflow: hidden, overflow-x: auto, or any scrollable overflow value is forbidden. overflow: visible is required so that dropdown sub-menu panels (P-12) can render below the nav bar without being clipped. Scrollbars do not appear because the flex container uses flex-wrap: nowrap and fixed height.P-12Dropdown sub-menu navigation pattern (mandatory). Every site nav must use the dropdown group structure. Each group is a
.site-nav-group element (position: relative) containing a .site-nav-group-trigger label and a .site-nav-dropdown panel that appears on hover. Individual doc links are .site-nav-dd-link elements inside the dropdown. Flat .site-nav-link items directly inside .site-nav-inner are forbidden. Active-state detection must target .site-nav-dd-link and add .has-active to the parent .site-nav-group.P-13Data model documents must contain a relationship diagram. Any document describing a data model — including
data-model.html, any schema specification, or any doc containing table definitions — must include a visual diagram of all tables and their relationships (foreign keys, cardinality). The diagram must use a sanctioned HTML/CSS component (P-07). A list of tables without a relationship diagram is a policy violation. The diagram must identify primary keys, foreign key links, and one-to-many vs. many-to-many cardinality.P-15Tables must never clip on overflow. Any
.tbl-wrap element must use overflow-x: auto. Using overflow: hidden silently clips wide tables on narrow viewports, cutting off the first column with no scroll affordance. This is a rendering defect, not a style choice. The validator enforces this rule on every HTML file.P-14Architecture documents must not contain table schema definitions. Table definitions, column lists, data types, primary/foreign keys, and schema DDL belong exclusively in
data-model.html (or the designated data model document). An architecture document — including architecture.html, NEXUS_HLD.html, ORCHESTRATION_PLAN.html, and any NEXUS_USECASE_*.html — may reference table names only in passing. It must not reproduce schema. Any table schema found in an architecture doc is a P-14 violation and must be moved to the data model document and replaced with a cross-reference link.P-16The
.site-nav{} root CSS selector must be present when .site-nav-inner CSS is defined. If a file defines .site-nav-inner { ... } but omits the .site-nav { ... } selector, the sticky positioning, background, and backdrop-filter declarations are orphaned — the CSS parser discards them. The nav will not be sticky and will have no background. The validator checks all files that contain .site-nav-inner CSS for the presence of a .site-nav{} rule. Root cause: copy-paste truncation of the minified nav CSS block. Fixed in NEXUS_USECASE_ENDO.html and NEXUS_USECASE_ARC.html (2026-04-20).P-17Every
<table> in files that use .tbl-wrap must be wrapped in a <div class="tbl-wrap">. A bare table with no scroll wrapper clips silently on narrow viewports — the table overflows the container with no horizontal scroll affordance. The rule fires only on files that define .tbl-wrap in their CSS (i.e., files using the Nexus doc template). Exempt files: data-model.html, architecture.html, production-readiness.html, WORMWOOD_APP.html, index.html (pre-Nexus or non-tabular layout patterns). The validator checks for tbl-wrap appearing within 400 characters before each <table> tag.P-18Every file containing
.flow-diagram CSS must declare overflow-x:hidden on both html and body. Flow diagram nodes use flex-shrink:0 with a fixed min-width. When the total node width exceeds the viewport, the flex row expands the document width, producing a full-page horizontal scrollbar. overflow-x:hidden on html clips at the viewport boundary without creating a new scroll container; adding it to body as well prevents any remaining block-level overflow. Without both declarations the page is horizontally scrollable on any viewport narrower than the combined node width. The validator requires at least two overflow-x:hidden declarations in any file that defines .flow-diagram.P-19The
.flow-diagram CSS class is forbidden in all HTML documents — zero tolerance. .flow-diagram (horizontal flexbox node-arrow-node layout) is the deprecated diagram pattern. It is superseded by the ww-diagram node graph (P-07). Any HTML file containing a .flow-diagram CSS rule will be rejected by validate_doc_policy.py and blocked from S3 publication by RUN_publish_docs.py. Root cause of prohibition: the flexbox layout does not scale to graph topologies and produced full-width horizontal overflow on narrow viewports. Introduced as a hard block after ISSUE-011 (2026-04-20).P-20
ww-diagram.js must include max-width:100% in the .wwd-outer CSS rule it injects at runtime. The SVG canvas rendered by ww-diagram.js is sized in pixels to fit the node graph layout. Without max-width:100% on the .wwd-outer wrapper, the canvas expands to its full pixel width and overflows the parent .page container (max-width: 960px), producing content that extends past the text column on every page that contains a diagram. RUN_publish_docs.py reads docs/ww-diagram.js directly and asserts the property is present before any S3 publish is permitted. Root cause of requirement: ISSUE-012, discovered 2026-04-20 after diagrams were published to S3 without the constraint.P-21No local filesystem paths in published HTML documents. Any absolute Windows path (e.g.
E:\repos\UV\Nexus, C:\repos\) in an HTML file exposes internal development machine structure in a client-facing document. All such paths must be replaced with repo-relative paths (e.g. nexus/, chameleonv2/) before publication. The validator detects any pattern matching a drive letter followed by a colon and backslash then repos (regex: [A-Za-z]:\repos), and also file:/// URIs referencing local file paths. Both cause a gate exit 1. Root cause of requirement: ISSUE-013, discovered 2026-04-20.P-22Mockup visual fidelity grading — minimum Level 3 for publication. All mockup/wireframe documents (
*_MOCKUPS.html) must meet a minimum fidelity grade before publication. Grading scale: Level 1 — Lo-fi wireframe (boxes/outlines only, no colour, no effects). Level 2 — Mid-fi wireframe (correct layout, basic colour tokens, no effects). Level 3 — Hi-fi static (correct colour tokens from P-09, border-radius, gradient fills, backdrop-filter/glassmorphism, proper typography scale, box shadows matching the styling guide for that product). Level 4 — Hi-fi interactive (Level 3 plus hover states, CSS transitions/animations, animated borders, skeleton loaders, cursor interaction feedback). Minimum for publication: Level 3. Mockups must visually match the documented styling guide (*_STYLING.html) for the same product area. Required fidelity markers at Level 3+: (a) backdrop-filter: blur() on glassmorphism panels, (b) radial/linear gradient backgrounds matching theme spec, (c) border-radius matching component pattern specs, (d) correct CSS variable colour tokens (not approximations), (e) box-shadow with glow on interactive elements, (f) typography using declared font stack and scale. The mockup document header must declare its fidelity level in the doc-tag element (e.g. “Level 4 Hi-fi Interactive Mockup”). The validator checks for the presence of backdrop-filter, box-shadow, and at least one @keyframes rule in any *_MOCKUPS.html file; absence of all three triggers a warning. Root cause of requirement: NEXUS_APP_MOCKUPS.html v1.0 shipped as flat wireframe (Level 1) despite existing STY-HUB-01 styling guide documenting full glassmorphism + animated border system. Discovered 2026-05-04.02 — Documentation Sitemap
All sanctioned documents in the Nexus docs directory. Every file listed is a nav destination.
Strategy
NEXUS_PRODUCT_PLAN.htmlMaster product plan, roadmap, use cases, stack
NEXUS_LEAFLET.htmlOne-page product overview
NEXUS_EXEC_BRIEF.htmlExecutive summary for commercial conversations
Architecture
NEXUS_HLD.htmlHigh-level design, four-scale model
NEXUS_WBS.htmlWork breakdown structure
WORMWOOD_APP.htmlCanvas interaction architecture
architecture.htmlNexus rule engine architecture (legacy ref)
data-model.htmlData model reference (legacy ref)
Use Cases
NEXUS_USECASE_NESTO.htmlUC1: Nesto UAE worker onboarding
NEXUS_USECASE_ENDO.htmlUC2: ENDO AI three pipelines
NEXUS_USECASE_ARC.htmlUC3: ARC freelance CRM pipelines
Platform
NEXUS_BACKLOG.htmlNode implementation backlog BL01–BL25
NEXUS_ACTION_PLAN.htmlAudit, ordered actions A-01–A-12, policy
NEXUS_DOC_POLICY.htmlThis document: documentation standards P-01–P-14
NEXUS_DOC_HIERARCHY.htmlDocument authority hierarchy: 6-tier conflict resolution, complete registry
ORCHESTRATION_PLAN.htmlM-ORCH milestone spec: orchestration platform, multi-tenant model, node taxonomy
ROADMAP_IDEAS.htmlEngineering ideas backlog feeding milestone planning
NEXUS_DEMO_VISION.htmlAutonomous demo mode vision. Governs BL19–BL25 implementation.
architecture.htmlNexus rule engine architecture reference
data-model.htmlNexus data model reference
production-readiness.htmlNexus production readiness reference
03 — Sanctioned Diagram: ww-diagram
The only permitted diagram in Nexus HTML documents is the ww-diagram node graph rendered by ww-diagram.js. All other diagram representations — including .flow-diagram flexbox boxes — are forbidden and will be rejected by the validator.
| Element | Required value | Notes |
|---|---|---|
| Container | <div class="ww-diagram" data-wwd="[graph-id]"></div> |
Rendered by ww-diagram.js into an absolutely-positioned canvas with SVG edge lines. |
| Graph data | <script type="application/json" id="[graph-id]">{ layout, nodes, edges }</script> |
layout: array of rows (each row = array of node IDs). nodes: [{id, label, cat, sub?, info?}]. edges: [{from, to, pt?, label?}]. |
Node categories (cat) |
CLIENT • API • CORE • STORE • ADMIN • EXTERNAL • DOMAIN • SECURITY • PIPELINE |
Each category has a fixed accent colour defined in ww-diagram.js. Do not invent new categories. |
Edge pin types (pt) |
data • ctrl • class • rule • prop • sse |
Controls edge colour. Omit pt for default (data). Optional label on edge for annotation. |
| Script include | <script src="ww-diagram.js"></script> |
Must appear before </body>. One include per page — multiple diagrams supported via distinct data-wwd IDs. |
| Forbidden pattern | Why forbidden | Validator rule |
|---|---|---|
.flow-diagram CSS class | Horizontal flexbox node-arrow boxes. Wraps awkwardly on narrow viewports. Visually inconsistent with ww-diagram node graphs. | P-19: validator rejects any file containing .flow-diagram in CSS. |
| Mermaid / D3 / Chart.js | External libraries not in the approved stack. | P-07 explicit prohibition. |
| SVG or PNG diagrams | Not editable as text. Cannot be version-controlled meaningfully. | P-07 explicit prohibition. |
| ASCII / Unicode box-drawing art | Not rendered consistently across fonts. | P-01 explicit prohibition. |
04 — Status Pill Reference
| Pill | Meaning | Conditions Required |
|---|---|---|
| Complete | Fully done. UI built, backend built, tested, demo-able end to end. | UI exists. API exists. Tests pass. Can be demonstrated live. |
| Backend Only | API/backend exists. No UI, no canvas wire-up, no demo-able frontend. | Backend code merged and tested. Frontend not started or not connected. |
| CLI Only | Functionality exists but only through command-line scripts, not the platform API or UI. | Script works. No API endpoint. No UI. |
| Rules Only | Nexus rules defined. No executor node, no pipeline integration. | Rule file exists. No API. No executor. |
| Not Started | Nothing exists. Not designed, not coded, not tested. | Zero code. Zero tests. Zero UI. |
05 — Nav Compliance Checklist
Before any HTML document is committed, verify all of the following:
C-01site-nav CSS present in <style> block. Required classes:
.site-nav, .site-nav-inner, .site-nav-brand, .site-nav-sep, .site-nav-group, .site-nav-group-trigger, .site-nav-dropdown, .site-nav-dd-link. Flat .site-nav-link inside .site-nav-inner is forbidden (P-12).C-02site-nav HTML present in <body> as the first element, before any content div. Must include brand, separators, group labels, and links matching the sitemap.
C-03Active-link JS snippet present. The IIFE that reads
window.location.href and adds nav-active class to the matching link must be present after the nav HTML.C-04No pre blocks with ASCII art. Grep for
<pre> tags in the file. Any pre block containing tree characters, box-drawing chars, or ASCII flow art must be replaced with a sanctioned diagram component.C-05No emoji characters. Scan full file content for Unicode ranges U+1F300–U+1F9FF, U+2600–U+27BF. Zero tolerance.
C-06All status claims are accurate. Every
pill-green element must represent something that can be demonstrated live. Use pill-warn BACKEND ONLY if only the API exists.06 — Audit & Consistency Protocol
Run this audit whenever a new document is added or an existing document is changed. All checks must pass before a document is considered policy-compliant.
A-01Verify the document is listed in both sitemaps. Every
.html file in docs/ must appear in the sitemap of NEXUS_ACTION_PLAN.html (Section 06) and NEXUS_DOC_POLICY.html (Section 02). Unlisted files are policy violations.A-02Verify the document is linked in the site-nav. New Platform docs must be added to the Platform dropdown in all active nav docs simultaneously. The NEXUS_DOC_HIERARCHY.html complete registry must also be updated.
A-03Verify the document has a site-nav (P-02). Run
validate_doc_policy.py. A document with no .site-nav element is a P-02 violation. Exception: files in the validator’s _P02_EXEMPT list (declared legacy orphans awaiting user classification decision).A-04Verify authority tier assignment. Every new document must be assigned to a tier in NEXUS_DOC_HIERARCHY.html Section 06 (Complete Document Registry). Unclassified documents are policy violations.
A-05Run the validator before committing.
.\.venv\Scripts\python.exe scripts\validate_doc_policy.py must exit 0. Any non-zero exit is a blocker.A-06Cross-check status claims against the Tier 1 audit. If a document claims a milestone is Complete (green pill) and NEXUS_ACTION_PLAN.html Section 03 marks it LIE or NOT STARTED, the claim must be corrected before the document is committed.