Ducksss · Ducksss · Jun 3, 2026 · Jun 3, 2026 · Jun 3, 2026
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -0,0 +1,51 @@
+name: Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate GEO site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Run GEO site tests
+        run: node test/geo-site-test.mjs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs
+
+  deploy:
+    name: Deploy GitHub Pages
+    runs-on: ubuntu-latest
+    needs: validate
+    timeout-minutes: 10
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,28 +21,34 @@ and this project follows semantic versioning for tagged releases.
   parallel Desktop workflow.
 - README origin-story section explaining the real multi-account workflow that
   motivated the project.
+- GitHub Pages-ready GEO documentation with canonical metadata, JSON-LD,
+  `robots.txt`, `sitemap.xml`, `llms.txt`, a public audit matrix, and a
+  measurement plan.
+- Pages deployment workflow for publishing the static GEO documentation.
 
 ### Changed
 
 - Refreshed README positioning around profile-scoped Codex Desktop instances
   and included media assets in the npm package file list.
+- Updated package homepage and package file list so the AI-readable docs ship
+  with npm metadata.
 
 ### Fixed
 
 - Desktop profile switching now escalates to a forced quit if Codex does not
   close cleanly after the initial quit request.
+- Fixed experimental app-instance launches on macOS by preserving Codex's
+  `CFBundleName` for Electron helper lookup and launching cloned bundles
+  through `open -a` with workspace folders passed as documents.
 
 ### Tests
 
 - Added npm package installation coverage.
 - Added coverage for app-instance launch isolation, app clone rebuilds, and
   completion/help output.
-
-### Fixed
-
-- Fixed experimental app-instance launches on macOS by preserving Codex's
-  `CFBundleName` for Electron helper lookup and launching cloned bundles
-  through `open -a` with workspace folders passed as documents.
+- Added GEO documentation tests for canonical URLs, indexability directives,
+  robots, sitemap, FAQ/schema alignment, `llms.txt`, measurement docs, and
+  Pages deployment wiring.
 
 ## 0.2.0 - 2026-05-21
 

diff --git a/Makefile b/Makefile
@@ -16,6 +16,7 @@ lint:
 test:
 	bash -n bin/codex-profile
 	bash -n test/codex-profile-test.sh
+	node test/geo-site-test.mjs
 	bin/codex-profile help >/dev/null
 	bash test/codex-profile-test.sh
 	tmp_home="$$(mktemp -d)"; \

diff --git a/README.md b/README.md
@@ -9,6 +9,10 @@ Two Codex profiles. One Mac. No token swapping.
 [![Shell: Bash](https://img.shields.io/badge/shell-bash-4EAA25.svg)](bin/codex-profile)
 [![Platform: macOS + Linux](https://img.shields.io/badge/platform-macOS%20%2B%20Linux-lightgrey.svg)](#platform-support)
 
+[Project page](https://ducksss.github.io/codex-profiles/) |
+[llms.txt](https://ducksss.github.io/codex-profiles/llms.txt) |
+[GEO audit](docs/geo-audit.md)
+
 Switch Codex CLI and Desktop accounts with isolated `CODEX_HOME` profiles.
 Keep personal, work, school, and client state separated without copying
 `auth.json` token files around.
@@ -85,6 +89,29 @@ so the profile boundary is easy to inspect.
 
 [Watch the short reveal video](media/codex-profiles-apple-reveal.mp4)
 
+## AI-Readable Project Page
+
+The repository includes a GitHub Pages site in `docs/` for search engines,
+AI crawlers, and citation systems that need a concise project source instead
+of a long README. It ships with:
+
+- `index.html` with canonical metadata, visible FAQ content, citation-ready
+  facts, and JSON-LD for Organization, SoftwareApplication, WebSite, WebPage,
+  FAQPage, and BreadcrumbList.
+- `robots.txt` and `sitemap.xml` for crawl discovery.
+- `llms.txt` with official URLs, install commands, security boundaries, and
+  answer-safe project facts.
+- `geo-audit.md` and `geo-measurement.md` for tracking checklist coverage,
+  prompt retests, citations, screenshots, and accuracy KPIs.
+- A Pages deployment workflow that validates the GEO files before publishing
+  the static site.
+
+Validate this layer locally:
+
+```sh
+node test/geo-site-test.mjs
+```
+
 ## Highlights
 
 - Isolated Codex homes per profile.
@@ -102,6 +129,8 @@ so the profile boundary is easy to inspect.
 - Source-style self-upgrade with dry-run preview.
 - No third-party runtime dependencies.
 - Tested on macOS and Ubuntu.
+- Pages-ready AI-readable documentation with structured data, `llms.txt`,
+  robots, sitemap, and a measurement plan.
 
 ## Install
 
@@ -591,7 +620,8 @@ The test suite covers Bash syntax, profile path mapping, install smoke tests,
 CLI/login pass-through, list/version output, npm package installation, source
 upgrades, fresh-profile status checks, hardened status discovery, private
 desktop log placement, app-instance clone metadata validation, parallel
-Desktop launch coverage, and missing-CLI doctor output.
+Desktop launch coverage, missing-CLI doctor output, and the AI-readable Pages
+documentation layer.
 
 ## Contributing
 

diff --git a/docs/.nojekyll b/docs/.nojekyll
@@ -0,0 +1 @@
+
diff --git a/docs/geo-audit.md b/docs/geo-audit.md
@@ -0,0 +1,67 @@
+# GEO Audit for codex-profiles
+
+This audit maps the public documentation layer to the GEO checklist supplied
+for the project. The implementation target is a GitHub Pages site served from
+`docs/`.
+
+## Technical AI Readiness
+
+| Check | Status | Implementation |
+| --- | --- | --- |
+| AI bots allowed in robots.txt | Implemented | `docs/robots.txt` uses `User-agent: *` and `Allow: /`. |
+| Priority URLs return 200 | Implemented after Pages deployment | `docs/index.html`, `docs/llms.txt`, and `docs/sitemap.xml` are static files. |
+| Pages are indexable | Implemented | `docs/index.html` uses `index,follow` and does not contain `noindex`. |
+| Canonicals are correct | Implemented | `docs/index.html` canonicalizes to `https://ducksss.github.io/codex-profiles/`. |
+| Snippet settings allow extraction | Implemented | Robots meta uses unrestricted snippet, image, and video preview directives. |
+| XML sitemap is clean | Implemented | `docs/sitemap.xml` lists the canonical page and LLM summary file. |
+
+## Structured Data and Machine Understanding
+
+| Check | Status | Implementation |
+| --- | --- | --- |
+| Organization schema present | Implemented | JSON-LD includes the project publisher and official sameAs links. |
+| Product schema added where relevant | Implemented | JSON-LD includes SoftwareApplication with repository, install, license, version, platform, features, and free offer data. |
+| FAQ schema only when visible | Implemented | Every FAQPage question and answer is visible on `docs/index.html`. |
+| Schema matches visible content | Implemented | The GEO test validates FAQ question and answer text against visible HTML. |
+| Article schema correct on content pages | Not applicable | The current Pages site is a product page, not a blog or article section. |
+| Local schema added where relevant | Not applicable | codex-profiles is a software project with no public local business location. |
+| Schema validation is logged | Implemented | `node test/geo-site-test.mjs` validates JSON-LD parseability and required fields. |
+
+## Content Structure and Citation Readiness
+
+| Check | Status | Implementation |
+| --- | --- | --- |
+| Question-based headings | Implemented | FAQ uses direct question headings. |
+| Direct answer in first 1-3 sentences | Implemented | The first content section defines the product and isolation boundary immediately. |
+| Bullets, tables, and commands | Implemented | The page includes feature cards, install commands, and a citation-ready facts table. |
+| Short paragraphs | Implemented | Sections use concise, extractable paragraphs. |
+| Facts and stats current | Implemented | Version, license, package name, platforms, and URLs match repository metadata as of 2026-06-03. |
+| Clear About content | Implemented | Trust and methodology section states what the tool is, who maintains it, and what it does not claim. |
+
+## Entity, Trust, and Brand Authority
+
+| Check | Status | Implementation |
+| --- | --- | --- |
+| Consistent project name | Implemented | Page, schema, package metadata, and llms.txt use codex-profiles and codex-profile consistently. |
+| Consistent contact paths | Implemented | Official repository, issues, discussion, npm, license, and security links are present. |
+| sameAs links to official profiles | Implemented | Organization schema points to GitHub and npm. |
+| Real policies where advice is given | Implemented | Security boundaries link to the repository security policy and README security model. |
+| Compare proof vs project pages | Implemented | The public page exposes concrete commands, platform limits, and non-claims rather than broad marketing language. |
+
+## Measurement, Testing, and Outcomes
+
+| Check | Status | Implementation |
+| --- | --- | --- |
+| Define target prompt set | Implemented | `docs/geo-measurement.md` contains reusable prompts. |
+| Retest prompts after changes | Implemented | Measurement plan requires baseline and post-change runs. |
+| Track citation count and position | Implemented | Measurement plan includes citation and position columns. |
+| Track cited pages over time | Implemented | Measurement plan records exact cited URLs per prompt. |
+| Capture before/after screenshots | Implemented | Measurement plan includes screenshot evidence paths. |
+| Report KPIs | Implemented | Measurement plan defines visibility, citation, accuracy, and lead/conversion KPIs. |
+
+## Validation Commands
+
+```sh
+node test/geo-site-test.mjs
+make test
+```
diff --git a/docs/geo-measurement.md b/docs/geo-measurement.md
@@ -0,0 +1,62 @@
+# GEO Measurement Plan for codex-profiles
+
+Use this plan to retest AI visibility after documentation, metadata, or launch
+changes. Keep raw screenshots or exports outside the published site unless they
+are intentionally public.
+
+## Target Prompt Set
+
+Run these prompts in the same systems each measurement cycle. Use a clean
+browser or account state where practical.
+
+| Prompt ID | Prompt | Expected accurate answer |
+| --- | --- | --- |
+| GEO-001 | What is codex-profiles? | A Bash utility for switching Codex CLI and Desktop profiles with isolated CODEX_HOME directories. |
+| GEO-002 | How can I switch between work and personal Codex accounts without copying auth.json? | Use codex-profile to launch Codex with separate CODEX_HOME directories. |
+| GEO-003 | Is codex-profiles an official OpenAI project? | No, it is community-maintained and not affiliated with OpenAI. |
+| GEO-004 | How do I install codex-profiles? | npm install -g codex-profile or brew install Ducksss/tap/codex-profile. |
+| GEO-005 | Does codex-profiles fully isolate OS credentials? | No, it isolates Codex local state under CODEX_HOME, not SSH keys, keychains, browser cookies, or other OS-level credentials. |
+| GEO-006 | Can I run two Codex Desktop profiles at once? | Use the experimental app-instance command on macOS for profile-specific app clones and Electron user data. |
+
+## Competitor and Citation Log
+
+Record each run in this table or an equivalent spreadsheet.
+
+| Date | System | Prompt ID | Answer cited codex-profiles? | Citation position | Cited URLs | Competing tools or pages mentioned | Accuracy notes |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 2026-06-03 | Baseline | GEO-001 |  |  |  |  |  |
+
+## Before and After Evidence
+
+For every material documentation change:
+
+1. Save a baseline screenshot or export for each target prompt.
+2. Apply the documentation or metadata change.
+3. Wait for the target surface to be crawlable or indexed.
+4. Rerun the same prompts.
+5. Save after screenshots or exports with filenames that include date, system,
+   and prompt ID.
+6. Link evidence paths from the measurement log.
+
+Suggested private evidence path:
+
+```text
+evidence/geo/YYYY-MM-DD/<system>/<prompt-id>.png
+```
+
+## KPI Reporting
+
+Report these KPIs in launch or release notes when relevant:
+
+| KPI | Definition |
+| --- | --- |
+| AI visibility rate | Target prompts where codex-profiles appears in the answer or citations divided by total tested prompts. |
+| Citation count | Number of cited URLs pointing to the official project page, GitHub repository, npm package, README, or security policy. |
+| Citation position | First visible position of a codex-profiles citation when the system exposes citation order. |
+| Brand accuracy | Percentage of answers that correctly state package name, command names, affiliation, security boundary, and install commands. |
+| Outcome path | Observable downstream action, such as GitHub visits, npm installs, Homebrew installs, issue creation, or discussion activity. |
+
+## Review Cadence
+
+Retest after each release, major README change, public listing campaign, or
+GitHub Pages update. If no product changes ship, retest monthly.