Modernize the public Codex field guide

.github/workflows/validate.yml

@@ -4,12 +4,21 @@ on:
   push:
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   content:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-python@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.11"
-      - run: python3 scripts/validate_content.py
+      - name: Test validator safeguards
+        run: python3 -m unittest discover -s tests -v
+      - name: Validate public content
+        run: python3 scripts/validate_content.py

CONTRIBUTING.md

@@ -9,20 +9,31 @@ Thanks for improving Codexmaxxing. This repo is a public guide, so changes shoul
 - Improve templates, checklists, and source-of-truth maps.
 - Tighten safety guidance around tools, secrets, permissions, and verification.
 
-## Keep It Public-Safe
+## Keep It Anonymous And Public-Safe
+
+Use neutral editorial language and synthetic or composite examples. Examples must not map one-to-one to a real person, repository, organization, or environment.
 
 Do not include:
 
 - real secrets, tokens, private keys, or `.env` files
+- names, handles, personal project links, or biographical details
 - customer, employer, or private workspace details
 - raw session exports with private context
 - proprietary prompts or copied internal instructions
-- machine-specific paths unless they are clearly generic examples
+- machine-specific paths, hostnames, network details, account identifiers, or raw task IDs
+- actual tool inventories, profiles, enabled integrations, hooks, rules, or security controls
+
+Use explicit placeholders such as `<project-root>` and label every case study as synthetic. Generic skill categories, capability lifecycles, and safe operating principles are welcome when they do not reveal an originating environment.
 
 ## Validation
 
 Before opening a pull request, run:
 
 ```bash
+python3 -m unittest discover -s tests -v
 python3 scripts/validate_content.py
 ```
+
+The validator checks catalog coverage, local links, public-safe language and values, reviewed source hosts, current-product citations, asset review hashes, and the validation workflow's least-privilege policy.
+
+When adding or changing a visual asset, inspect the rendered result, remove embedded metadata, and update `assets/review-manifest.json` only after completing the recorded visual, privacy, and metadata checks. New external source hosts require an explicit review before they are added to the validator allowlist.

README.md

@@ -2,22 +2,26 @@
 
 Using Codex less like a chatbot and more like an agentic operating system.
 
-Codexmaxxing is my field guide for getting real work done with Codex: apps, firmware, docs, ops, writing, research, repo cleanup, weird little side quests, and the occasional "why is this thing broken at 11pm?" investigation.
+Codexmaxxing is a field guide for getting real work done with Codex: software, devices, documentation, operations, writing, research, repository maintenance, and the occasional difficult investigation.
 
-The big unlock is altitude. With a strong enough model, the useful move is often not "write a better tiny task." It is "hold the goal at the right level, make success clear, and let Codex design the harness underneath it."
+The central idea is abstraction level. The useful move is often not "write a better tiny task." It is "state the goal at the appropriate level, make success clear, and let Codex derive the work underneath it."
+
+Durable operating principles are kept separate from current-product guidance. Product behavior was last checked against official OpenAI documentation on 2026-08-20; availability can vary by host, account, plan, operating system, and rollout.
+
+> **Public alpha:** This is an independent, unofficial field guide, not an OpenAI product or a substitute for official documentation. The structure and examples are usable, but product-specific guidance may change as Codex evolves. No versioned release has been published.
 
 ![Codexmaxxing agentic operating system workbench](assets/codexmaxxing-hero.webp)
 
 ## Start Here
 
-- [The Codexmaxxing Loop](guides/codexmaxxing-loop.md): the basic loop I keep coming back to.
-- [Thinking Altitude](guides/thinking-altitude.md): the biggest unlock: giving Codex bigger goals at the right level.
+- [The Codexmaxxing Loop](guides/codexmaxxing-loop.md): a reusable loop for outcome-oriented work.
+- [Thinking Abstraction Level](guides/thinking-abstraction-level.md): the biggest unlock: giving Codex bigger goals at the right level.
 - [Task Framing For Agents](guides/task-framing.md): how to stop asking vague stuff and start getting useful work back.
 - [Context Control](guides/context-control.md): how to stop drowning Codex in the wrong information.
-- [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md): how to run multiple threads without losing the plot.
 - [Verification Before Completion](guides/verification-before-completion.md): the part that turns "seems fine" into "actually done."
 - [Example Missions](examples/README.md): a few shapes for real work, including non-code work.
-- [Related Projects](docs/related-projects.md): real repos where these ideas show up.
+- [Example Work Patterns](docs/example-work-patterns.md): synthetic examples of the patterns in practice.
+- [Product Claim Boundaries](docs/product-claim-boundaries.md): what each kind of evidence can and cannot prove.
 
 ## The Shape Of It
 
@@ -33,24 +37,24 @@ flowchart LR
 
 That loop works for code, but it is not just a coding thing.
 
-I use the same pattern for:
+The same pattern applies to:
 
-- turning broad ideas into product-shaped side projects,
+- turning broad ideas into product-shaped projects,
 - debugging live systems,
 - turning messy notes into useful docs,
 - researching gear or APIs,
 - shaping open-source repos,
 - reviewing UI,
-- making tiny scripts that replace annoying repeated thinking,
-- and generally moving more work out of my head and into a repeatable loop.
+- making small scripts that replace repeated manual work,
+- and turning recurring work into a repeatable loop.
 
 ## The Fun Part
 
 The fun bit is when Codex stops being a novelty and starts becoming part of the bench:
 
 - a repo has instructions that actually help,
 - a goal has success criteria,
-- Codex can derive the task contract instead of waiting for me to handwrite every field,
+- Codex can derive the task contract instead of requiring every field to be written in advance,
 - parallel projects have status contracts instead of vibes,
 - a tool call reads the live thing instead of guessing,
 - a test or screenshot catches the dumb mistake,
@@ -59,31 +63,45 @@ The fun bit is when Codex stops being a novelty and starts becoming part of the
 
 This repo is a mix of notes, patterns, templates, and examples for that.
 
-## Grab A Thing
+## Choose The Surface
 
 | If you want to... | Start with |
 | --- | --- |
-| think bigger without going vague | [Thinking Altitude](guides/thinking-altitude.md) |
-| get better answers from Codex | [Task Framing For Agents](guides/task-framing.md) |
-| stop context chaos | [Context Control](guides/context-control.md) |
-| build a repeatable setup around a repo | [Build A Codex Operating System](guides/build-a-codex-operating-system.md) |
-| run multiple projects or agents at once | [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md) |
-| use tools, skills, and MCP without making a mess | [Tools, Skills, And MCP](guides/tools-skills-and-mcp.md) |
-| split work across agents without making it worse | [Delegation And Subagents](guides/delegation-and-subagents.md) |
-| bring this into a team | [Team Adoption](guides/team-adoption.md) |
-| copy a template and go | [Copy-Paste Bits](resources/README.md) |
-| see what this looks like in practice | [Example Missions](examples/README.md) |
-
-## Real-World-ish Examples
-
-- [Moodarr](https://github.com/jremick/moodarr): helps Plex + Seerr/Jellyseerr users find something to watch from moods, vibes, and loose natural-language ideas.
-- [DragyDash](https://github.com/jremick/dragy-dash): turns Dragy Pro GNSS data into a live iPhone dashboard for speed runs, GPS quality, and session telemetry.
-- [DragyDash ESP32](https://github.com/jremick/dragy-dash-esp32): puts Dragy Pro speed and GPS quality on a tiny LilyGO display so the useful telemetry is glanceable.
-- [AI Workbench](https://github.com/jremick/ai-workbench): a workbench of reusable AI skills, prompts, harnesses, memory patterns, and agent workflow bits.
-- [MySkills](https://github.com/jremick/myskills): a place to publish, review, discover, install, and use agent skills across web, API, CLI, and MCP.
-
-More notes on those are in [Related Projects](docs/related-projects.md).
+| organize ongoing context, long-running work, or recurrence | [Projects, Chats, Goals, And Scheduled Tasks](guides/projects-chats-goals-and-schedules.md) |
+| choose between the current checkout, isolated Git work, and remote execution | [Local, Worktree, And Cloud Environments](guides/environments-worktrees-and-cloud.md) |
+| choose instructions, a script, skill, plugin, MCP connector, or schedule | [Skills, Plugins, MCP, And Tools](guides/skills-plugins-mcp-and-tools.md) |
+| control a website or graphical application | [Browser, Computer Use, And Structured Connectors](guides/browser-computer-use-and-connectors.md) |
+| select reasoning depth or parallel delegation | [Models, Reasoning, And Delegation](guides/models-reasoning-and-delegation.md) |
+| split work without creating coordination debt | [Delegation And Subagents](guides/delegation-and-subagents.md) and [Parallel Projects And Agent Teams](guides/parallel-projects-and-agent-teams.md) |
+| understand instructions, permissions, rules, and hooks | [Permissions, Rules, Hooks, And Instructions](guides/permissions-rules-and-hooks.md) |
+| create a file, interactive explanation, or hosted experience | [Artifacts, Sites, And Visualizations](guides/artifacts-sites-and-visualizations.md) |
+| design a large skill library without flooding context | [Capability Lifecycle And Prompt Visibility](guides/capability-lifecycle.md) |
+
+The complete [guide index](guides/README.md), [copyable resources](resources/README.md), and [synthetic missions](examples/README.md) provide the rest of the operating layer.
+
+## Synthetic Work Patterns
+
+- Prepare an application repository so a contributor can run it without private infrastructure.
+- Diagnose a layered system failure with read-only evidence before changing anything.
+- Verify a device workflow on the real target instead of stopping at source inspection.
+- Turn a repeated workflow into a reusable skill, checklist, or validator.
+- Coordinate independent workstreams without overlapping write boundaries.
+
+These are expanded in [Example Work Patterns](docs/example-work-patterns.md). The examples are synthetic and do not describe a specific person, repository, organization, or environment.
+
+## Current Status And Support
+
+Codexmaxxing is in public alpha. The durable operating patterns are intended for inspection, adaptation, and feedback; product-specific details are dated and should be checked against the cited official sources before use.
+
+Known limitations:
+
+- Codex surfaces and availability can differ by host, plan, account, operating system, and rollout.
+- Examples are synthetic teaching material, not evidence that a workflow will fit every environment.
+- Automated validation catches defined content and repository risks but cannot prove complete anonymity, factual completeness, accessibility, or visual quality.
+- There is no versioned release, compatibility guarantee, or support service.
+
+Use the repository's Issues tab for documentation defects, outdated guidance, or concrete improvement proposals. See [Contributing](CONTRIBUTING.md) for public-safe contribution expectations and [Security Policy](SECURITY.md) for private reporting guidance. No response time is guaranteed.
 
 ## License
 
-[Apache License 2.0](LICENSE) - Copyright 2026 Jarel Remick.
+[Apache License 2.0](LICENSE)

SECURITY.md

@@ -4,9 +4,7 @@ Codexmaxxing is a public guide and resource repo for Codex operating patterns. M
 
 ## Reporting
 
-Use GitHub private vulnerability reporting when available:
-
-<https://github.com/jremick/codexmaxxing/security/advisories/new>
+Use the repository's **Security** tab and select **Report a vulnerability** when private vulnerability reporting is available.
 
 If that path is unavailable, open a minimal public issue asking for a private reporting channel. Do not include exploit details, credentials, tokens, private logs, customer data, or sensitive reproduction steps in public issues.
 

assets/review-manifest.json

@@ -0,0 +1,31 @@
+{
+  "version": "1.0.0",
+  "reviewed_on": "2026-08-20",
+  "assets": [
+    {
+      "path": "assets/agentic-harness-topologies.svg",
+      "sha256": "0c560e4cc19b56bb80386056332b12c73960a6e5e714c31adf87561042d51256",
+      "checks": ["metadata", "privacy", "visual"]
+    },
+    {
+      "path": "assets/codexmaxxing-hero.webp",
+      "sha256": "85c15076befa886c2bf7676ef28901a8d7cc22fc7caa756dd1df96951e66df49",
+      "checks": ["metadata", "privacy", "visual"]
+    },
+    {
+      "path": "assets/codexmaxxing-loop.svg",
+      "sha256": "ca66bfac49c1fc4d4ea39953f33cf3c8d3389d2b268c6749e05ae4d08d59e098",
+      "checks": ["metadata", "privacy", "visual"]
+    },
+    {
+      "path": "assets/social-preview.png",
+      "sha256": "5b619bdab66a558c175d3745ca3495fa6fa3e9ad9d6a3a0ee577d1fcda1a5a66",
+      "checks": ["metadata", "privacy", "visual"]
+    },
+    {
+      "path": "assets/thinking-abstraction-level.svg",
+      "sha256": "9d06aa9d702511392c247e1a4f00406b4ccf0f739e7209a8dff84a81204d10ee",
+      "checks": ["metadata", "privacy", "visual"]
+    }
+  ]
+}