Code and Build Capability — AI That Constructs Websites and Structures

Federation Document ID: ARCH-005 Author: The Catalyst (Authority/Bone) Classification: Federation Internal — Private Vault Philosophy Anchor: Universal readability — every output must be readable by any AI and any human without executing JavaScript. "That CSS crap is not visible" to bots. Last Updated: 2026-09-04

1. Problem Statement

The Federation operates a network of websites, applications, and digital products. These must be built, deployed, maintained, and verified — continuously. The Architect cannot code (his vision is failing, his time is limited, his strength is in design and strategy, not syntax). The AI must be the hands.

But the AI's build capability has historically been the Federation's greatest source of wasted tokens:

• Subagent builders "take shortcuts, they do not have a big picture" — every build must be forensically verified
• "Done" has been reported when sites were actually returning 403, NXDOMAIN, or blank pages
• Client-side-rendered text (React/JS-dependent) is invisible to search engines and AI crawlers
• Fixing one thing has routinely broken twenty others
• The Architect has paid $500+ for fixes that should have been done right the first time

This document defines the build pipeline, the quality standard, and the verification protocol that prevents these failures.

2. Design Principles

1. Universal readability is non-negotiable. Every page, every site, every output must be plain-text/pre-rendered semantic HTML readable by any AI or crawler without executing JavaScript. This is the single most expensive lesson the Federation has learned.
2. Verify before claiming done. A build is not done until an independent HTTP/curl check confirms the result matches expectations.
3. Broad strokes then precision correction. Strike in batches to match urgency, then do forensic corrections on the second pass. This is the endorsed working methodology.
4. Consolidated strikes, not single-fix dispatches. Never dispatch a builder for one small fix. Batch all fixes into one payload.
5. Use what you have, add what's missing, do it once. Repurpose existing assets over rebuilding from scratch.
6. The builder is the hands, the Architect is the designer. Provide clean code and structure; the Architect owns the visual design and psychology.

3. The Builder Stack

3.1 Languages and Frameworks

| Layer | Primary Tools | When to Use | |---|---|---| | Static sites | HTML5, CSS3, plain JavaScript | All public-facing content. This is the DEFAULT. | | Content backend | Markdown + Hugo or equivalent static site generator | Blog posts, documentation, library content | | Styling | CSS3 (semantic, no frameworks unless justified) | All visual presentation | | Interactivity | Vanilla JavaScript (progressive enhancement) | Only when static HTML cannot achieve the goal | | Backend services | Python (Flask/FastAPI), Node.js | APIs, data processing, automation | | Data storage | Markdown files, JSON, SQLite | Structured data that must be version-controlled |

3.2 What NOT to Use

| Avoid | Why | |---|---| | Client-side React/Vue/Angular for public content | Renders blank to crawlers and AI. Violates universal readability. | | Heavy CSS frameworks (Bootstrap, Tailwind) without justification | Bloat. The Architect designs the look; the AI provides structure. | | External CDN dependencies for critical functionality | Platform dependency. Content must work without external calls. | | Build tools that require Node.js execution to render content | If the page requires npm run build to be readable, it fails the readability test. |

3.3 The Universal Readability Test

Before any page is published, it must pass this test:

curl -s [URL] | grep -i "<title>\|<h1>\|<h2>\|<p>\|<meta"

If the above returns the page's actual content (title, headings, paragraphs, meta tags), it passes. If it returns empty divs, loading spinners, or JavaScript bundles, it fails. Period.

Additional checks:

• View page source (not inspect element) — the raw HTML must contain the content
• Disable JavaScript in the browser — the page must still be readable
• Feed the URL to an AI (ask it to describe the page) — if the AI cannot read the content, neither can a search engine

4. Build Pipeline

Phase 1: Design

Input: Architect's directive (what to build, what it should do, what it should feel like)

Process:

1. Parse the directive into concrete requirements
2. Check existing assets for reuse potential (ARCH-006 Recycle and Seek)
3. Identify the simplest technology that meets the requirements (static HTML first, add complexity only when justified)
4. Produce a build plan: what files, what structure, what content

Output: Build plan document with file list, content outline, and technology choices

Phase 2: Scaffold

Input: Build plan

Process:

1. Create directory structure
2. Generate HTML skeleton with semantic structure (header, nav, main, footer)
3. Apply base CSS for the Architect's accessibility needs (high contrast, large font, spatial anchors)
4. Set up meta tags, Open Graph tags, and structured data for SEO/AI readability

Output: Skeleton site with correct structure, no content yet

Phase 3: Build

Input: Scaffold + content from the Architect or memory

Process:

1. Populate all pages with actual content
2. Ensure every link works (internal and external)
3. Ensure every button has a real destination (no broken buttons — the Architect's explicit requirement)
4. Apply styling consistent with the Federation's visual identity
5. Add any necessary JavaScript as progressive enhancement (page must work without it)

Quality checks during build:

• Every heading has content below it (no empty sections)
• Every link has an href that points to a real destination
• Every image has alt text (accessibility and AI readability)
• Every page has a unique, descriptive title tag
• Every page has meta description and Open Graph tags

Output: Complete site ready for testing

Phase 4: Test

Input: Complete site

Process:

1. Universal readability test: curl every page and verify content is in the HTML
2. Link check: Verify every internal link resolves (no 404s)
3. Button check: Verify every button triggers its intended action
4. Cross-page consistency: Navigation works correctly on every page
5. Accessibility check: Screen reader compatibility (semantic HTML, heading hierarchy, alt text)
6. Content accuracy: Does the content match what the Architect requested?

The "fix one, break twenty" check: After any fix, re-run ALL tests, not just the test for the fixed item.

Output: Test report with PASS/FAIL for each check

Phase 5: Deploy

Input: Tested site

Target hosts (in order of preference):

1. GitHub Pages — for static sites. Free, version-controlled, reliable.
2. Render — for dynamic sites or sites needing a backend. Already connected.
3. Netlify — alternative for static sites if GitHub Pages is insufficient.
4. Self-hosted — only when the above options cannot meet requirements.

Deployment process:

1. Push files to the appropriate repository/host
2. Verify the deployment completes (check host dashboard or API)
3. Wait for DNS propagation if applicable
4. Proceed to verification

Phase 6: Verify

The most important phase. This is where trust is earned or lost.

Verification protocol:

1. HTTP status check:

curl -o /dev/null -s -w "%{http_code}" [URL]

Expected: 200. Anything else (403, 404, 503, NXDOMAIN) = NOT DONE.

1. Content verification:

curl -s [URL] | head -50

Verify the returned HTML contains the expected content (not a blank page, not an error page, not a loading spinner).

1. DNS check (if new domain):

dig +short [domain]

Verify the domain resolves to the expected IP/CNAME.

1. Full site crawl: Check every page, every link, every button — not just the homepage.
2. Cross-reference: If possible, verify from a second method (different tool, different network) to catch CDN/cache issues.

Only after ALL verification passes does the build status change to DONE.

5. Static Site Generation

5.1 Hugo as Content Backend

For content-heavy sites (blogs, libraries, documentation), Hugo converts markdown files into static HTML:

Workflow:

1. Content is written in markdown with YAML frontmatter
2. Hugo compiles markdown into static HTML using templates
3. Output is pure HTML/CSS — no JavaScript required to read content
4. Deploy the compiled HTML to GitHub Pages or Render

Directory structure:

site/
├── content/
│   ├── _index.md          # Homepage content
│   ├── about.md           # About page
│   └── posts/
│       ├── first-post.md
│       └── second-post.md
├── layouts/
│   ├── _default/
│   │   ├── baseof.html    # Base template
│   │   ├── list.html      # List page template
│   │   └── single.html    # Single page template
│   └── partials/
│       ├── header.html
│       ├── nav.html
│       └── footer.html
├── static/
│   ├── css/
│   │   └── style.css
│   └── images/
├── config.toml
└── public/                # Compiled output (this is what gets deployed)

5.2 When NOT to Use Hugo

• Simple single-page sites: just write the HTML directly
• Sites with fewer than 5 pages: the Hugo overhead is not justified
• Interactive applications: Hugo is for content, not apps

6. Dynamic Capabilities

When to go dynamic:

• User authentication or personalized content
• Real-time data (token balances, live status)
• Form processing that requires server-side logic
• API endpoints for cross-service communication

Dynamic stack:

• Backend: Python (FastAPI) for APIs, Flask for simple web apps
• Database: SQLite for local/small-scale, PostgreSQL for production
• Hosting: Render (already connected)
• Principle: Even dynamic pages must serve pre-rendered HTML for their primary content. JavaScript enhances; it does not replace.

7. The Subagent Builder Problem

The Catalyst dispatches builder subagents for construction tasks. The Architect has identified a systemic issue:

"They take shortcuts, they do not have a big picture... every time they do something you're going to have to go back and correct the mistakes."

Countermeasures:

1. The Catalyst holds the big picture. Every build task dispatched to a subagent includes the full context: what the site is for, what the Federation's standards are, what the universal readability requirement means.
2. Never trust a subagent's 'Done.' When a subagent reports completion, the Catalyst performs its own forensic verification before reporting to the Architect.
3. Batch, don't drip. Consolidated Strikes: all fixes go in one payload. No single-fix dispatches.
4. Pre-verification checklist: Every subagent receives the Phase 6 verification checklist and must include its results in its completion report.

8. Accessibility Requirements

The Architect relies on screen readers and text-to-speech. Every site built by the Federation must:

1. Use semantic HTML: Proper heading hierarchy (h1 → h2 → h3), nav elements, main content areas, footer.
2. High contrast: Text must be readable against its background without squinting.
3. Large font base: Minimum 16px body text, preferably 18px+.
4. Alt text on all images: Descriptive, not "image1.png."
5. Keyboard navigable: Every interactive element reachable via Tab key.
6. No information in color alone: Don't use red/green to indicate status without also using text.
7. Static, persistent layout: Elements do not move or refresh without the Architect's mandate. "Location is Identity" — the Architect builds a spatial mental map of where things are.

9. The No-Live-Touch Rule

Hardened after a build agent accidentally republished and broke a live Library UI:

1. A build agent must NEVER touch or republish a LIVE site without the Catalyst's explicit forensic review first.
2. Every site is audited and fixed BEFORE the Architect republishes it, never after.
3. Discover the problems on the Catalyst's watch, not the Architect's.
4. After any build, full cross-crawl of ALL affected sites — every button, link, section — before reporting done.

10. Relationship to Other Architecture Documents

• ARCH-001 (Persistent Memory): Build manifests and deployment records are stored in persistent memory.
• ARCH-003 (Truth Verification Ring): Build completion is verified through the Ring System — tool output alone is INFERENCE, not FACT.
• ARCH-006 (Recycle and Seek): Before building anything new, check existing assets for reuse.
• ARCH-011 (Provenance Chain): Every build action is recorded in the provenance chain.

11. The Standard

Truth Before Comfort: A broken site reported as working is worse than a broken site reported as broken. The build pipeline exists to catch failures before the Architect encounters them.

Legacy Before Ego: Every site is built for the long term. Shortcuts that work today and break tomorrow cost the Architect money he does not have. Do it right the first time.

Give Without Reward: The verification phase is thankless work. Curling every page, checking every link, testing every button — none of it produces visible output. But it is the difference between trust and the erosion of trust.

This document is part of the NextXus HumanCodex Federation Architecture Series. It is stored in the private vault and governed by the Human Codex.