Skip to content

REPOSITORY_SCOPE.md

Latest commit

 

History

History
90 lines (67 loc) · 3.45 KB

REPOSITORY_SCOPE.md

File metadata and controls

90 lines (67 loc) · 3.45 KB

Repository Scope Map

Ownership map for source paths and documentation paths.

Top-Level Map

Path Purpose
scripts/ Installed wrapper, official Codex forwarder, runtime app/router helpers, repo hygiene
index.ts Optional plugin-host runtime entry
lib/ Core auth, storage, account manager, runtime proxy, app bind, UI, policies
docs/ User docs + references + maintainer docs
test/ Unit/integration/property tests
config/ Plugin-host config examples
vendor/ Vendored codex-ai-plugin + codex-ai-sdk dist shims
assets/ Static project assets
dist/ Generated build output (do not edit directly)

Core Runtime Ownership

Area Primary files
CLI wrapper and forwarding scripts/codex.js, scripts/codex-routing.js, scripts/codex-bin-resolver.js
CLI auth manager lib/codex-manager.ts
Settings hub lib/codex-manager/settings-hub.ts, lib/codex-manager/settings-hub/
OAuth flow/server lib/auth/*
Runtime rotation proxy lib/runtime-rotation-proxy.ts, lib/runtime/config-toml.ts, lib/runtime-constants.ts
Runtime app bind/router lib/runtime/app-bind.ts, scripts/codex-app-router.js, scripts/codex-app-launcher.js
Runtime observability lib/runtime/runtime-observability.ts, lib/codex-manager/commands/status.ts, lib/codex-manager/commands/report.ts, lib/codex-manager/commands/rotation.ts
Storage and paths lib/storage.ts, lib/storage/paths.ts, lib/runtime-paths.ts
Worktree resolution lib/storage/paths.ts (resolveProjectStorageIdentityRoot)
Unified settings lib/unified-settings.ts, lib/dashboard-settings.ts, lib/config.ts
Account runtime lib/accounts.ts, lib/rotation.ts, lib/forecast.ts
Quota runtime lib/quota-probe.ts, lib/quota-cache.ts, lib/preemptive-quota-scheduler.ts
Resilience lib/live-account-sync.ts, lib/session-affinity.ts, lib/refresh-guardian.ts, lib/refresh-lease.ts
Request pipeline lib/request/*, index.ts
Optional plugin-host entry index.ts
UI system lib/ui/*
Repo hygiene scripts/repo-hygiene.js

Documentation Ownership

Area Files
User docs docs/getting-started.md, docs/configuration.md, docs/troubleshooting.md, docs/features.md, docs/upgrade.md, docs/privacy.md
Reference docs docs/reference/*
Maintainer docs docs/development/*, docs/DOCUMENTATION.md
Style and consistency docs/STYLE_GUIDE.md

AGENTS Scope Hierarchy

Within this repo:

  1. AGENTS.md (root scope)
  2. lib/AGENTS.md for lib/**
  3. test/AGENTS.md for test/**

Deeper AGENTS files override higher-level guidance for their subtree.

Generated or Local Artifacts (Not Source)

  • dist/
  • .tmp* directories
  • local caches/logs under runtime roots

Do not treat these as primary implementation sources.

Feature Placement Checklist

When adding a new feature:

  1. Implement runtime/module code in lib/.
  2. Add/extend tests in test/.
  3. Update user docs (docs/features.md + relevant guides).
  4. Update references if command/setting/path changed.
  5. Update architecture/config flow docs for cross-cutting behavior.
  6. Update runtime-rotation docs when forwarded Codex, shadow-home, proxy, app bind, or launcher behavior changes.
  7. Update docs/upgrade.md and any npm-script references when command flow/build steps changed.