Initial commit

Author: mizcausevic-dev

.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - project/aeo-registry
+  pull_request:
+
+jobs:
+  test:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+      - run: npm ci
+      - run: npm run verify

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+screenshots/*.log

CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [1.0.0] - 2026-05-15
+
+### Released
+- Published **aeo-registry** as a public TypeScript and Express registry for manifest readiness, claim-surface review, and publisher portfolio posture.
+- Packaged the implementation, browser-rendered proof assets, validation flow, and docs into a repo that treats AEO inventory as an operating system concern instead of a folder of disconnected specs.
+- Clarified the core problem the project is addressing: once AEO programs scale, weak manifests stay live because nobody owns freshness, source coverage, or answer-surface readiness centrally.
+
+### Why this mattered
+- Existing SEO and schema tooling helps teams publish assets, but it does not always give them a durable registry of what is actually safe to expose.
+- AEO teams need something closer to package governance: an index of manifests, claims, and publishers that can be reviewed before weak entries degrade trust.
+- This release turns that gap into a visible control-plane problem.
+
+## [0.1.0] - 2026-02-27
+
+### Shipped
+- Cut the first coherent internal version of the registry with manifest records, claim queues, and publisher summaries.
+- Anchored the system around freshness, source coverage, and answer-surface readiness instead of around simple file existence.
+- Established the route and payload shape used by the public version.
+
+## [Prototype] - 2025-08-12
+
+### Built
+- Built the first runnable prototype for indexing AEO manifests and scoring them by readiness.
+- Tested the concept against the kinds of failures that appear in scaling answer-engine programs: stale `llm.txt`, shallow citations, and uneven publisher hygiene.
+- Confirmed that a registry lens was more useful than another single-manifest validator.
+
+## [Design Phase] - 2024-04-23
+
+### Designed
+- Framed the system around operator visibility and publisher accountability rather than around individual authoring workflows.
+- Chose examples that made sense for infrastructure, SaaS, fintech, and vertical answer-surface programs.
+- Defined the output as something a content or AEO lead could review quickly.
+
+## [Idea Origin] - 2023-06-28
+
+### Observed
+- The original idea surfaced while looking at how answer-surface programs accumulate manifest sprawl without accumulating equal governance.
+- The recurring pattern was that manifest production was easy to start and difficult to keep coherent at scale.
+
+## [Background Signals] - 2022-10-18
+
+### Context
+- Earlier work around search, knowledge packaging, and evidence-backed publishing made one pattern obvious: if answer assets are not indexed and scored somewhere central, weak ones tend to remain live by default.
+- That pattern shaped the thinking behind this repo well before the public version existed.

README.md

@@ -0,0 +1,73 @@
+# AEO Registry
+
+TypeScript and Express registry for **tracking AEO manifests, publisher readiness, claim surfaces, and citation-safe discovery posture**.
+
+> **What this repo proves**
+>
+> AEO work gets much more durable when manifests are not just published, but indexed, reviewed, and held to a clear readiness bar for freshness, source coverage, and answer-surface integrity.
+
+## Why this repo exists
+
+Most AEO programs eventually end up with more manifests than they can reason about cleanly. One team publishes `llm.txt`. Another emits JSON-LD. A vertical site adds FAQ schema. A support team pushes answer-packaging metadata. Without a registry, those assets exist, but nobody has a single view of which ones are fresh, which ones are weakly sourced, and which ones should never have been exposed to answer engines in the first place.
+
+`aeo-registry` turns that sprawl into an operator-friendly inventory. It tracks manifests by publisher, version, freshness, source coverage, and answer-surface footprint, then keeps the claims and portfolios that need review visible before they degrade trust or citation quality.
+
+## Screenshots
+
+![Overview](./screenshots/01-overview-proof.png)
+![Registry board](./screenshots/02-registry-proof.png)
+![Claim board](./screenshots/03-claims-proof.png)
+![Verification](./screenshots/04-verification-proof.png)
+
+## What it includes
+
+- Express app with HTML proof surfaces and JSON APIs
+- sample manifest inventory across AEO infrastructure, fintech, SaaS, and real estate
+- readiness scoring for freshness, source coverage, and answer-surface completeness
+- claim review queue for blocked and review-level surfaces
+- publisher portfolio posture for multi-manifest programs
+- real browser-rendered README proof assets captured from the running app
+- Vitest coverage plus demo and smoke validation scripts
+
+## Local run
+
+```powershell
+Set-Location "C:\Users\chaus\dev\repos\aeo-registry"
+npm install
+npm run dev
+```
+
+Open:
+
+- [http://127.0.0.1:5084/](http://127.0.0.1:5084/)
+- [http://127.0.0.1:5084/registry](http://127.0.0.1:5084/registry)
+- [http://127.0.0.1:5084/claims](http://127.0.0.1:5084/claims)
+- [http://127.0.0.1:5084/publishers](http://127.0.0.1:5084/publishers)
+- [http://127.0.0.1:5084/verification](http://127.0.0.1:5084/verification)
+- [http://127.0.0.1:5084/docs](http://127.0.0.1:5084/docs)
+
+## Validation
+
+```powershell
+npm run verify
+npm run render:assets
+```
+
+## API routes
+
+- `GET /api/dashboard/summary`
+- `GET /api/manifests`
+- `GET /api/claims`
+- `GET /api/publishers`
+- `GET /api/sample`
+
+## Repo layout
+
+```text
+src/
+  data/
+  services/
+docs/
+scripts/
+screenshots/
+```

docs/ORIGIN.md

@@ -0,0 +1,27 @@
+# Why We Built This
+
+**aeo-registry** came from a pattern that shows up as soon as answer-engine work matures past a handful of experiments: the number of manifests grows faster than the team’s ability to govern them. One property has an `llm.txt`. Another publishes JSON-LD packages. A support site ships FAQ schema. A product catalog adds entity metadata. Over time, those assets start behaving like packages in a software supply chain, but most teams still manage them more like isolated files or one-off launch tasks.
+
+That becomes a real operating problem. A manifest can still exist and still be weak. A claim can still be extractable and still be under-cited. A publisher can still be shipping answer-surface metadata even while its freshness posture is drifting out of bounds. Traditional SEO tooling helps with parts of the surface. Schema validators help with syntax. Linting helps a single manifest at a time. What often remains missing is a **registry view** that answers the broader program-level questions:
+
+- which manifests are actually ready to be trusted
+- which claim surfaces are getting stale
+- which publishers are carrying the most readiness risk
+- which entries should be blocked before they degrade answer quality
+
+We built **aeo-registry** to make that operating layer visible. The repo is intentionally centered on portfolio posture rather than on authoring mechanics. It assumes that manifests already exist or can be produced elsewhere. The real challenge is deciding whether those manifests are fresh enough, sourced enough, and coherent enough to stay live across answer surfaces.
+
+Existing tools missed the mark for understandable reasons. Manifest validators are usually local and file-specific. Search tooling often focuses on performance after publication. Content systems focus on authoring, not package governance. The missing layer is the one that treats manifests as a managed inventory with statuses, queues, ownership, and release discipline.
+
+That shaped the design philosophy:
+
+- **operator-first**
+  so the registry feels like a review queue, not a passive index
+- **publisher-legible**
+  so a content or AEO lead can immediately see portfolio pressure
+- **claim-aware**
+  so risky answer surfaces stay visible, not hidden inside aggregate scores
+- **readiness-driven**
+  so manifests have to earn public exposure instead of getting it by default
+
+The current version uses sample registry data, but the underlying point is practical: answer-engine infrastructure needs indexing and governance, not just creation. Next on the roadmap are manifest diff views, exportable readiness policies, and stronger linkage into the rest of the Kinetic Gain AEO stack.

docs/architecture.md

@@ -0,0 +1,59 @@
+# Architecture
+
+## Overview
+
+`aeo-registry` is a TypeScript and Express application that treats AEO manifests as managed registry entries instead of as disconnected files.
+
+The repo models three layers:
+
+1. **manifest inventory**
+   - publisher, version, canonical URL, and vertical
+   - freshness, source coverage, entity count, and answer-surface coverage
+   - readiness state across `ready`, `review`, and `blocked`
+
+2. **claim review**
+   - individual claim surfaces that can become stale or under-cited
+   - source-count and freshness pressure
+   - next-action guidance for registry operators
+
+3. **publisher posture**
+   - portfolio summaries for multi-manifest programs
+   - blocked counts, average source coverage, and freshness risk
+   - a quick view of which publisher programs need attention first
+
+## Runtime shape
+
+- `src/data/sampleRegistry.ts`
+  - sample manifest, claim, and publisher state
+- `src/services/registryService.ts`
+  - summary, sorting, and payload composition logic
+- `src/services/render.ts`
+  - HTML control surfaces for the registry
+- `src/app.ts`
+  - Express routes for HTML and JSON outputs
+
+## Primary routes
+
+- `/`
+  - overview and lead recommendation
+- `/registry`
+  - manifest inventory board
+- `/claims`
+  - claim-surface queue
+- `/publishers`
+  - publisher portfolio posture
+- `/verification`
+  - top-line proof summary
+- `/docs`
+  - route and payload map
+
+## Validation approach
+
+- `vitest`
+  - verifies the registry summary and ordering logic
+- `scripts/run_demo.ts`
+  - renders a deterministic JSON snapshot of the current registry state
+- `scripts/smoke_check.ts`
+  - boots the app and confirms that core HTML and JSON routes respond correctly
+- `scripts/render_readme_assets.ps1`
+  - captures real browser screenshots from the running app for README proof