Skip to content

docs: uh.agenticeng.app site, code map, old site retired, 1.0 release audit - #250

Draft
LaloLalo1999 wants to merge 7 commits into
mainfrom
claude/branch-audit-1.0-prep-k697wg
Draft

docs: uh.agenticeng.app site, code map, old site retired, 1.0 release audit#250
LaloLalo1999 wants to merge 7 commits into
mainfrom
claude/branch-audit-1.0-prep-k697wg

Conversation

@LaloLalo1999

@LaloLalo1999 LaloLalo1999 commented Sep 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

This PR adds a new documentation site in apps/site/ for https://uh.agenticeng.app, retires the old one, and records an audit of every branch and open PR ahead of a coordinated 1.0 release.

Preview: https://uh-site-preview.eduardo-lalo1999.workers.dev (redeployed on each push to this PR).

What's in it

  • Site. Built with Astro Starlight and served as static files from Cloudflare Workers.
    • Guides: the lifecycle, an architecture map, the .harness/ artifact and schema inventory, adapters, supervision and the guard, teams, observability, surfaces, and the CLI reference.
    • scripts/sync-docs.mjs mirrors docs/, specs/ and CHANGELOG.md into the site on every build, so the site can't drift from the repo.
  • Code map and explorer. Generated with Understand-Anything (MIT, pinned 6df3065) from the v0.11 stack tip.
    • The graph covers 235 files: 1,391 nodes, 3,745 edges, 10 layers and a 14-step tour.
    • The Code map pages are generated from apps/site/codemap/knowledge-graph.json.
    • /explorer/ hosts the dashboard's static build.
  • Road to 1.0. A branch and PR audit, a 25-item debt register, and a phased release plan with the owner decisions and stack status.
  • Old site retired.
    • Removed: apps/docs, deploy-docs.yml and scripts/sync-docs-site.mjs.
    • The npm homepage and the plugin theme assets now point at uh.agenticeng.app.
    • apps/site/redirect/ is a 301 Worker for the old domain. It gets deployed by hand once the old Worker is removed.
  • Workflow. deploy-site.yml builds on PRs, deploys a preview to uh-site-preview on workers.dev, and deploys production from main.

Owner decisions

  • Capability checks warn by default, and --strict blocks.
  • GitNexus is optional.
  • 0.10.0 is skipped and folded into 0.11.0.
  • The old site is retired.
  • Stack fixes go to the bottom layer (v0.11.0 (1/10): supervision, guard and evidence hardening #240), not to main.
  • The Codex review bot stays on, reversing the earlier plan (2026-09-24). It needs code-review credits enabled before it can review the v0.11 stack.
  • Fixing the placeholder commit authors is pending. It needs a force-push of the stack, which waits on an explicit go-ahead.

Stack status (2026-09-24)

Testing

  • apps/site builds 104 pages, and a link and anchor check over the built HTML finds 0 broken internal links.
  • The explorer loads the graph in Chromium.
  • At the repo root, typecheck passes and test passes (74 files, 882 tests). CI is green on this PR.
  • GitNexus tools were not available in this session, and no existing symbols were edited on this branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6

@claude
docs: add uh.agenticeng.app documentation site with 1.0 release audit
40bbebc 
Add apps/site, an Astro Starlight static site served by Cloudflare Workers
static assets at uh.agenticeng.app, plus a Docs site workflow that builds
it on pull requests and deploys it from main with wrangler.

The repository's docs/, specs/ and CHANGELOG.md stay the single source of
truth: scripts/sync-docs.mjs mirrors them into the site on every build,
lifts the first heading into the page title and rewrites relative links to
site routes or GitHub, so the mirror cannot drift the way apps/docs did.

Hand-written guides cover the mental model, the lifecycle, an architecture
map, the .harness artifact and schema inventory, adapters, supervision and
the tool guard, teams, observability, surfaces and the CLI. A Road to 1.0
section records the 2026-09-23 branch and PR audit, a 25-item technical
debt register and a phased release plan, including the verified fix for the
v0.11 tool guard skipping POSIX absolute paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@claude
ci(site): build and deploy in one job without artifact upload
8b3aabe 
The Build site job failed at actions/upload-artifact because the
organization's Actions artifact storage quota is exhausted, after the site
itself built successfully. Deploy from the same workspace on main instead
of handing dist/ to a second job, so the workflow does not depend on
artifact storage at all.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@claude
docs: retire the old docs site and add Cloudflare preview deploys
a04ef5a 
Owner decisions recorded on 2026-09-23 (warn plus --strict for capability
checks, GitNexus optional, fix placeholder authors, skip 0.10.0, retire the
old site, turn off the Codex review bot).

- Remove apps/docs, deploy-docs.yml and scripts/sync-docs-site.mjs; the
  apps/site mirror replaces them. Point the npm homepage and the Hermes
  plugin theme assets at uh.agenticeng.app, which now serves og.png,
  icon.svg and wordmark.svg (those URLs were already broken on the old
  site).
- Pull requests deploy a preview with `wrangler deploy --env preview` to
  the workers.dev-only Worker uh-site-preview; main still deploys
  production. Fork PRs without secrets only build.
- Add apps/site/redirect, a Worker that 301s uh.agenticengineering.lat to
  the new site, deployed by hand once the old Worker releases the domain.
- Site pages record the decisions, the retirement steps and how to turn
  off the Codex review app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@claude
docs(site): add a generated code map and interactive explorer
939173f 
Run the Understand-Anything /understand pipeline (MIT,
Egonex-AI/Understand-Anything@6df3065) over the v0.11 stack tip with
the pending bottom-layer fixes: 235 files, 1,391 nodes, 3,745 edges,
10 architecture layers and a 14-step guided tour. Tests, fixtures,
acceptance and prose docs were excluded; inline validation reports no
issues.

- apps/site/codemap/knowledge-graph.json is the committed graph;
  scripts/sync-codemap.mjs turns it into the Code map section
  (overview, guided tour, hotspots, one page per layer) on every build
  and copies it next to the explorer.
- public/explorer/ is the dashboard's static demo build under
  /explorer/, with its MIT license; scripts/build-explorer.sh rebuilds
  it from the pinned commit. It loads only Google Fonts externally.
- The tour's cli.ts step is corrected: the file is meant to be a thin
  dispatcher but still holds ~2,400 lines of handler logic.
- contributing/site documents how to refresh the graph; the release
  plan records the tested-but-unpushed bottom-layer stack commits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@LaloLalo1999 LaloLalo1999 changed the title docs: uh.agenticeng.app documentation site + 1.0 release audit docs: uh.agenticeng.app site, code map, old site retired, 1.0 release audit Sep 23, 2026
@claude
docs(site): record the stack fixes as landed with green CI
e99cc2e 
The three bottom-layer commits are on #240 and merged up through #249
without force-pushes; CI is green on #240, #247 and #249. The release
plan now says so, marks the Phase 0 guard and flake items done, and
keeps the author rewrite as the one open owner decision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@claude
docs(site): past tense for the fixed guard bug in the release plan
462909b 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
@claude
docs(site): keep the Codex review bot on
5f82fbb 
The owner reversed the earlier decision: the ChatGPT Codex Connector
reviews are useful. The branch audit and release plan now say to keep
it, and note that it needs code-review credits enabled to review the
v0.11 stack, where it only posted usage-limit notices.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SCSUzdpgCLPbVws9ckbSV6
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@LaloLalo1999 @claude