codex-profile 0.2.0 → 0.3.0

package/bin/codex-profile

@@ -3,12 +3,13 @@
 set -euo pipefail
 
 PROGRAM="${0##*/}"
-VERSION="0.2.0"
+VERSION="0.3.0"
 CODEX_APP="${CODEX_APP:-/Applications/Codex.app}"
 CODEX_APP_BIN="${CODEX_APP_BIN:-$CODEX_APP/Contents/MacOS/Codex}"
 CODEX_BUNDLED_CLI="${CODEX_BUNDLED_CLI:-$CODEX_APP/Contents/Resources/codex}"
 CODEX_PROFILE_QUIT_ATTEMPTS="${CODEX_PROFILE_QUIT_ATTEMPTS:-30}"
 CODEX_PROFILE_QUIT_SLEEP="${CODEX_PROFILE_QUIT_SLEEP:-0.5}"
+CODEX_PROFILE_APP_INSTANCE_ROOT="${CODEX_PROFILE_APP_INSTANCE_ROOT:-$HOME/Library/Application Support/codex-profile/app-instances}"
 CODEX_PROFILE_UPGRADE_REPO="${CODEX_PROFILE_UPGRADE_REPO:-https://github.com/Ducksss/codex-profiles.git}"
 CODEX_PROFILE_UPGRADE_REF="${CODEX_PROFILE_UPGRADE_REF:-main}"
 
@@ -18,6 +19,7 @@ $PROGRAM - run Codex with isolated CODEX_HOME profiles
 
 Usage:
   $PROGRAM app <profile> [workspace]
+  $PROGRAM app-instance <profile> [--rebuild] [workspace]
   $PROGRAM cli <profile> [codex-args...]
   $PROGRAM login <profile> [codex-login-args...]
   $PROGRAM init <profile>
@@ -25,7 +27,7 @@ Usage:
   $PROGRAM status [profile]
   $PROGRAM status --json [profile]
   $PROGRAM path <profile>
-  $PROGRAM logs <profile> [--path|--tail [lines]]
+  $PROGRAM logs <profile> [--instance] [--path|--tail [lines]]
   $PROGRAM clone-config <source-profile> <target-profile> [--force]
   $PROGRAM list
   $PROGRAM doctor [--json]
@@ -37,6 +39,7 @@ Examples:
   $PROGRAM login personal
   $PROGRAM init work
   $PROGRAM app personal ~/Dev/my-project
+  $PROGRAM app-instance work --rebuild ~/Dev/client-project
   $PROGRAM cli personal exec "review this repo"
   $PROGRAM status
   $PROGRAM logs personal --tail 50
@@ -51,6 +54,7 @@ Environment:
   CODEX_APP       Override Codex.app path.
   CODEX_APP_BIN   Override Codex Desktop binary path.
   CODEX_CLI       Override Codex CLI binary path.
+  CODEX_PROFILE_APP_INSTANCE_ROOT  Override experimental app-instance clone root.
   CODEX_PROFILE_UPGRADE_REPO    Override upgrade repository.
   CODEX_PROFILE_UPGRADE_REF     Override upgrade git ref.
   CODEX_PROFILE_UPGRADE_CACHE   Override upgrade cache checkout.
@@ -133,6 +137,12 @@ codex_desktop_running() {
   return 1
 }
 
+force_quit_codex_app() {
+  osascript -e 'tell application "Codex" to quit' > /dev/null 2>&1 || true
+  pkill -x Codex > /dev/null 2>&1 || true
+  pkill -f "$CODEX_BUNDLED_CLI app-server" > /dev/null 2>&1 || true
+}
+
 codex_cli_error_message() {
   if [[ -n "${CODEX_CLI:-}" ]]; then
     printf 'CODEX_CLI is set but not executable: %s\n' "$CODEX_CLI"
@@ -174,7 +184,10 @@ find_codex_cli() {
 }
 
 quit_codex_app() {
-  local attempt
+  local attempt quit_attempts="$CODEX_PROFILE_QUIT_ATTEMPTS"
+
+  [[ "$quit_attempts" =~ ^[0-9]+$ ]] || quit_attempts=30
+  (( quit_attempts < 1 )) && quit_attempts=1
 
   if ! codex_desktop_running; then
     return 0
@@ -183,7 +196,17 @@ quit_codex_app() {
   note "Quitting existing Codex app..."
   osascript -e 'tell application "Codex" to quit' > /dev/null 2>&1 || true
 
-  for ((attempt = 0; attempt < CODEX_PROFILE_QUIT_ATTEMPTS; attempt++)); do
+  for ((attempt = 0; attempt < quit_attempts; attempt++)); do
+    if ! codex_desktop_running; then
+      return 0
+    fi
+    sleep "$CODEX_PROFILE_QUIT_SLEEP"
+  done
+
+  note "Codex did not quit cleanly; forcing shutdown..."
+  force_quit_codex_app
+
+  for ((attempt = 0; attempt < quit_attempts; attempt++)); do
     if ! codex_desktop_running; then
       return 0
     fi
@@ -215,7 +238,210 @@ command_app() {
 
   note "Launching Codex Desktop with CODEX_HOME=$codex_home"
   note "Log: $log_file"
-  (umask 077 && nohup env CODEX_HOME="$codex_home" "$CODEX_APP_BIN" "$workspace" > "$log_file" 2>&1 &)
+  (umask 077 && nohup env CODEX_HOME="$codex_home" "$CODEX_APP_BIN" > "$log_file" 2>&1 &)
+
+  local codex_cli
+  if codex_cli="$(try_find_codex_cli)"; then
+    (sleep 1 && env CODEX_HOME="$codex_home" "$codex_cli" app "$workspace" > /dev/null 2>&1 &)
+  fi
+}
+
+bundle_identifier_profile_suffix() {
+  local profile="$1"
+  local encoded
+
+  encoded="$(printf '%s' "$profile" | LC_ALL=C od -An -tx1 -v | tr -d '[:space:]')" || die "Cannot encode profile name for app instance bundle identifier."
+  printf 'p%s\n' "$encoded"
+}
+
+app_instance_bundle_identifier_for_profile() {
+  local profile="$1"
+  local bundle_suffix
+
+  bundle_suffix="$(bundle_identifier_profile_suffix "$profile")"
+  printf 'com.openai.codex.profile.%s\n' "$bundle_suffix"
+}
+
+app_instance_dir_for_profile() {
+  local profile="$1"
+
+  validate_profile "$profile"
+  printf '%s/%s\n' "$CODEX_PROFILE_APP_INSTANCE_ROOT" "$profile"
+}
+
+app_instance_app_for_profile() {
+  local profile="$1"
+  local instance_dir
+
+  instance_dir="$(app_instance_dir_for_profile "$profile")"
+  printf '%s/Codex %s.app\n' "$instance_dir" "$profile"
+}
+
+patch_app_instance_metadata() {
+  local profile="$1"
+  local app="$2"
+  local plist="$app/Contents/Info.plist"
+  local bundle_id display_name
+
+  [[ -f "$plist" ]] || die "Codex app clone is missing Info.plist: $plist"
+
+  bundle_id="$(app_instance_bundle_identifier_for_profile "$profile")"
+  display_name="Codex $profile"
+
+  if ! command -v plutil > /dev/null 2>&1; then
+    note "Warning: plutil not found; app instance metadata was not patched."
+    return 0
+  fi
+
+  plutil -replace CFBundleIdentifier -string "$bundle_id" "$plist" > /dev/null || die "Cannot patch app instance bundle identifier."
+  plutil -replace CFBundleDisplayName -string "$display_name" "$plist" > /dev/null || die "Cannot patch app instance display name."
+
+  if command -v codesign > /dev/null 2>&1; then
+    codesign --force --deep --sign - "$app" > /dev/null 2>&1 || die "Cannot re-sign app instance: $app"
+  else
+    note "Warning: codesign not found; patched app instance may not launch on macOS."
+  fi
+}
+
+app_instance_plist_value() {
+  local app="$1"
+  local key="$2"
+  local plist="$app/Contents/Info.plist"
+
+  [[ -f "$plist" ]] || return 1
+  command -v plutil > /dev/null 2>&1 || return 2
+  plutil -extract "$key" raw -o - "$plist" 2> /dev/null
+}
+
+app_instance_is_incompatible() {
+  local profile="$1"
+  local app="$2"
+  local plist="$app/Contents/Info.plist"
+  local bundle_id bundle_name display_name expected_bundle_id expected_display_name
+
+  [[ -f "$plist" ]] || return 0
+  command -v plutil > /dev/null 2>&1 || return 1
+
+  bundle_name="$(app_instance_plist_value "$app" CFBundleName)" || return 0
+  [[ "$bundle_name" == "Codex" ]] || return 0
+
+  expected_bundle_id="$(app_instance_bundle_identifier_for_profile "$profile")"
+  bundle_id="$(app_instance_plist_value "$app" CFBundleIdentifier)" || return 0
+  [[ "$bundle_id" == "$expected_bundle_id" ]] || return 0
+
+  expected_display_name="Codex $profile"
+  display_name="$(app_instance_plist_value "$app" CFBundleDisplayName)" || return 0
+  [[ "$display_name" == "$expected_display_name" ]] || return 0
+
+  return 1
+}
+
+create_app_instance_bundle() {
+  local profile="$1"
+  local instance_dir instance_app tmp_app source_bin
+
+  [[ -d "$CODEX_APP" ]] || die "Codex.app not found at $CODEX_APP"
+  source_bin="$CODEX_APP/Contents/MacOS/Codex"
+  [[ -x "$source_bin" ]] || die "Codex Desktop binary not found at $source_bin"
+
+  ensure_home "$CODEX_PROFILE_APP_INSTANCE_ROOT"
+  instance_dir="$(app_instance_dir_for_profile "$profile")"
+  ensure_home "$instance_dir"
+  instance_app="$(app_instance_app_for_profile "$profile")"
+  tmp_app="$instance_dir/.Codex $profile.app.tmp.$$"
+
+  rm -rf -- "$tmp_app"
+  cp -R "$CODEX_APP" "$tmp_app" || die "Cannot copy Codex.app to app instance: $tmp_app"
+  patch_app_instance_metadata "$profile" "$tmp_app"
+
+  if [[ -e "$instance_app" ]]; then
+    rm -rf -- "$instance_app" || die "Cannot replace app instance: $instance_app"
+  fi
+
+  mv "$tmp_app" "$instance_app" || die "Cannot install app instance: $instance_app"
+}
+
+ensure_app_instance_bundle() {
+  local profile="$1"
+  local rebuild="$2"
+  local instance_app instance_bin
+
+  instance_app="$(app_instance_app_for_profile "$profile")"
+  instance_bin="$instance_app/Contents/MacOS/Codex"
+
+  if [[ "$rebuild" == "yes" ]]; then
+    note "Rebuilding app instance for $profile"
+    create_app_instance_bundle "$profile"
+    return 0
+  fi
+
+  if [[ -x "$instance_bin" ]] && app_instance_is_incompatible "$profile" "$instance_app"; then
+    note "Rebuilding app instance for $profile because existing clone is incompatible"
+    create_app_instance_bundle "$profile"
+    return 0
+  fi
+
+  if [[ ! -x "$instance_bin" ]]; then
+    note "Creating app instance for $profile"
+    create_app_instance_bundle "$profile"
+  fi
+}
+
+command_app_instance() {
+  local profile="${1:-}"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM app-instance <profile> [--rebuild] [workspace]"
+  shift || true
+
+  local rebuild=no workspace=""
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --rebuild)
+        rebuild=yes
+        ;;
+      --)
+        shift
+        [[ "$#" -le 1 ]] || die "Usage: $PROGRAM app-instance <profile> [--rebuild] [workspace]"
+        workspace="${1:-}"
+        break
+        ;;
+      --*)
+        die "Usage: $PROGRAM app-instance <profile> [--rebuild] [workspace]"
+        ;;
+      *)
+        [[ -z "$workspace" ]] || die "Usage: $PROGRAM app-instance <profile> [--rebuild] [workspace]"
+        workspace="$1"
+        ;;
+    esac
+    shift
+  done
+
+  workspace="${workspace:-$PWD}"
+
+  local codex_home instance_app instance_bin user_data_dir log_dir log_file
+  codex_home="$(codex_home_for_profile "$profile")"
+  ensure_home "$codex_home"
+  ensure_app_instance_bundle "$profile" "$rebuild"
+
+  instance_app="$(app_instance_app_for_profile "$profile")"
+  instance_bin="$instance_app/Contents/MacOS/Codex"
+  [[ -x "$instance_bin" ]] || die "Codex app instance binary not found at $instance_bin"
+  command -v open > /dev/null 2>&1 || die "macOS open command not found; app-instance is macOS-only."
+
+  user_data_dir="$codex_home/electron-user-data"
+  ensure_home "$user_data_dir"
+
+  log_dir="$codex_home/logs"
+  log_file="$log_dir/desktop-instance.log"
+  ensure_home "$log_dir"
+  (umask 077 && : > "$log_file")
+  chmod 600 "$log_file" 2> /dev/null || true
+
+  note "Launching experimental Codex Desktop instance for $profile"
+  note "CODEX_HOME=$codex_home"
+  note "App bundle: $instance_app"
+  note "Electron user data: $user_data_dir"
+  note "Log: $log_file"
+  (umask 077 && open -n --env "CODEX_HOME=$codex_home" --stdout "$log_file" --stderr "$log_file" -a "$instance_app" "$workspace" --args "--user-data-dir=$user_data_dir") || die "Cannot launch app instance: $instance_app"
 }
 
 command_cli() {
@@ -542,14 +768,18 @@ command_path() {
 
 command_logs() {
   local profile="${1:-}"
-  [[ -n "$profile" ]] || die "Usage: $PROGRAM logs <profile> [--path|--tail [lines]]"
+  [[ -n "$profile" ]] || die "Usage: $PROGRAM logs <profile> [--instance] [--path|--tail [lines]]"
   shift || true
 
   local mode="cat"
+  local log_name="desktop.log"
   local lines=50
 
   while [[ "$#" -gt 0 ]]; do
     case "$1" in
+      --instance)
+        log_name="desktop-instance.log"
+        ;;
       --path)
         mode="path"
         ;;
@@ -564,7 +794,7 @@ command_logs() {
         die "Unknown logs option '$1'."
         ;;
       *)
-        die "Usage: $PROGRAM logs <profile> [--path|--tail [lines]]"
+        die "Usage: $PROGRAM logs <profile> [--instance] [--path|--tail [lines]]"
         ;;
     esac
     shift
@@ -572,16 +802,22 @@ command_logs() {
 
   [[ "$lines" =~ ^[0-9]+$ ]] || die "Tail line count must be a non-negative integer."
 
-  local codex_home log_file
+  local codex_home log_file missing_label
   codex_home="$(codex_home_for_profile "$profile")"
-  log_file="$codex_home/logs/desktop.log"
+  log_file="$codex_home/logs/$log_name"
+  missing_label="$log_name"
+  if [[ "$log_name" == "desktop.log" ]]; then
+    missing_label="desktop log"
+  elif [[ "$log_name" == "desktop-instance.log" ]]; then
+    missing_label="desktop instance log"
+  fi
 
   if [[ "$mode" == "path" ]]; then
     printf '%s\n' "$log_file"
     return 0
   fi
 
-  [[ -f "$log_file" ]] || die "No desktop log for $profile ($log_file)."
+  [[ -f "$log_file" ]] || die "No $missing_label for $profile ($log_file)."
 
   if [[ "$mode" == "tail" ]]; then
     tail -n "$lines" "$log_file"
@@ -872,12 +1108,12 @@ _codex_profile()
   command="${COMP_WORDS[1]}"
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
-    COMPREPLY=( $(compgen -W "app cli login init remove status path logs clone-config list doctor completions upgrade version help" -- "$cur") )
+    COMPREPLY=( $(compgen -W "app app-instance cli login init remove status path logs clone-config list doctor completions upgrade version help" -- "$cur") )
     return 0
   fi
 
   case "$command" in
-    app|cli|login|init|remove|status|path|logs)
+    app|app-instance|cli|login|init|remove|status|path|logs)
       if [[ "$COMP_CWORD" -eq 2 ]]; then
         profiles="$(codex-profile list 2>/dev/null)"
         COMPREPLY=( $(compgen -W "default personal work $profiles" -- "$cur") )
@@ -906,7 +1142,7 @@ EOF
 _codex_profile() {
   local -a commands profiles shells
   commands=(
-    app cli login init remove status path logs clone-config list doctor completions upgrade version help
+    app app-instance cli login init remove status path logs clone-config list doctor completions upgrade version help
   )
   profiles=(${(f)"$(codex-profile list 2>/dev/null)"} default personal work)
   shells=(bash zsh fish)
@@ -917,7 +1153,7 @@ _codex_profile() {
   fi
 
   case "$words[2]" in
-    app|cli|login|init|remove|status|path|logs)
+    app|app-instance|cli|login|init|remove|status|path|logs)
       if (( CURRENT == 3 )); then
         _describe 'profile' profiles
       fi
@@ -941,8 +1177,8 @@ EOF
     fish)
       cat <<'EOF'
 complete -c codex-profile -f
-complete -c codex-profile -n '__fish_is_first_arg' -a 'app cli login init remove status path logs clone-config list doctor completions upgrade version help'
-complete -c codex-profile -n '__fish_seen_subcommand_from app cli login init remove status path logs' -a '(codex-profile list 2>/dev/null) default personal work'
+complete -c codex-profile -n '__fish_is_first_arg' -a 'app app-instance cli login init remove status path logs clone-config list doctor completions upgrade version help'
+complete -c codex-profile -n '__fish_seen_subcommand_from app app-instance cli login init remove status path logs' -a '(codex-profile list 2>/dev/null) default personal work'
 complete -c codex-profile -n '__fish_seen_subcommand_from clone-config' -a '(codex-profile list 2>/dev/null) default personal work'
 complete -c codex-profile -n '__fish_seen_subcommand_from completions' -a 'bash zsh fish'
 EOF
@@ -1029,6 +1265,9 @@ main() {
     app)
       command_app "$@"
       ;;
+    app-instance)
+      command_app_instance "$@"
+      ;;
     cli)
       command_cli "$@"
       ;;

package/docs/.nojekyll

@@ -0,0 +1 @@
+

package/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
+```

package/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.