docs: harden and scope agent guidance

.github/AGENTS.md

@@ -0,0 +1,26 @@
+# GitHub automation instructions
+
+This file applies to `.github/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Security boundary
+
+Every workflow, ownership, branch-enforcement, release, or repository-automation
+change requires explicit security review under `MAINTAINERS.md`.
+
+## Workflow rules
+
+- Grant the minimum required `permissions`.
+- Pin third-party actions to immutable full commit SHAs.
+- Preserve the human-readable version comment beside each pinned action.
+- Do not run untrusted pull-request code with secrets or write permissions.
+- Treat `pull_request_target`, workflow dispatch, reusable workflows, artifacts, caches, and generated command input as trust boundaries.
+- Do not broaden triggers, write permissions, token exposure, release eligibility, or publish capability without an explicit task requirement.
+- Preserve cross-platform coverage where the workflow currently promises Linux, macOS, and Windows behavior.
+- Keep branch-enforcement text synchronized with `AGENTS.md`, `MAINTAINERS.md`, and the public contributing guide.
+
+## Validation
+
+- Inspect the complete workflow diff, including event triggers, permissions, conditions, interpolation, and shell behavior.
+- Run the local commands represented by changed workflow steps where possible.
+- Run `bun run prepush` for CI, release, dependency, packaging, or cross-platform workflow changes.
+- Do not claim the workflow itself passed until GitHub Actions reports success for the exact commit.

.github/CODEOWNERS

@@ -14,5 +14,7 @@
 /src/server/management-api.ts @lidge-jun @Ingwannu
 
 # Governance and security policy
+/AGENTS.md @lidge-jun @Ingwannu
+**/AGENTS.md @lidge-jun @Ingwannu
 /MAINTAINERS.md @lidge-jun @Ingwannu
 /SECURITY.md @lidge-jun @Ingwannu

AGENTS.md

@@ -16,12 +16,16 @@ Bun-native TypeScript with no separate server compile step.
   `tests/helpers/`, broader scenarios in `tests/e2e-style/`.
 - `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
 - `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
+- `go/` — Go native runtime (primary on the `dev2-go` line during transition).
 - `structure/` — maintainer invariants and architecture notes; read before
   changing shared subsystems.
 - `scripts/` — release and maintenance tooling; `scripts/release.ts` is the
   release authority.
 - `devlog/` — planning and investigation artifacts (mostly gitignored).
 
+Read the nearest nested `AGENTS.md` before changing files in a scoped
+directory (`src/`, `gui/`, `docs-site/`, `scripts/`, `.github/`).
+
 ## Commands
 
 ```bash

docs-site/AGENTS.md

@@ -0,0 +1,30 @@
+# Documentation-site instructions
+
+This file applies to `docs-site/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Source-of-truth rules
+
+- `docs-site/` is the public user-documentation source.
+- Document current shipped or intentionally pending behavior. Do not copy claims from historical `docs/` or `devlog/` material without verifying them against current code and configuration.
+- English documentation is the canonical source. Translated content must not contradict it.
+- Keep commands, paths, configuration keys, defaults, branch names, and URLs synchronized with the repository.
+- Do not edit generated build output.
+
+## Editing rules
+
+- Reuse the existing Astro and Starlight structure, navigation, components, and style.
+- Update all directly affected pages when a user workflow changes.
+- Do not add duplicated policy text when a stable canonical document can be linked instead.
+- Use repository-relative links for repository files and site-relative links for documentation pages where the existing site does so.
+
+## Required validation
+
+Run:
+
+```bash
+cd docs-site
+bun install --frozen-lockfile
+bun run build
+```
+
+Do not claim documentation validation passed unless this build completes successfully.

gui/AGENTS.md

@@ -1,5 +1,14 @@
 # OpenCodex GUI — agent rules
 
+This file applies to `gui/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Ownership and generated output
+
+- `gui/` is the React + Vite dashboard.
+- `gui/dist/` is generated packaged output. Do not edit it by hand.
+- Use the existing component, state, routing, styling, and data-access patterns before introducing a new abstraction.
+- Keep dashboard behavior aligned with the management API and provider configuration model.
+
 ## Text and i18n
 
 - **No hardcoded visible UI text** in `src/pages`, `src/components`, `src/App.tsx`, or `src/ui.tsx`.
@@ -19,7 +28,33 @@
   - Keep **code comments** (including shell `# …` comments in samples). Never strip them to “satisfy” i18n.
 - Run `bun run lint:i18n` after UI copy changes; fix real violations before committing. If a hit is technical, extend the allowlist or put the string in `<pre>`/`<code>` — do not invent nonsense translation keys.
 
+## Implementation rules
+
+- Preserve accessibility: keyboard operation, labels, focus behavior, semantic controls, and readable validation errors.
+- Do not introduce a dependency for behavior already provided by the current stack or a small local implementation.
+- Dependency changes require explicit security review.
+- Update `docs-site/` when dashboard behavior, setup, or configuration changes for users.
 
 ## Failure mode
 
 Hardcoding English (or German) in JSX to “fix” a bad translation is **not** allowed. Add or fix the key in all locale files instead.
+
+## Required validation
+
+Run all of the following for every functional `gui/` change:
+
+```bash
+cd gui
+bun test tests
+bun run lint
+bun run build
+```
+
+After any UI-copy or locale change, also run:
+
+```bash
+cd gui
+bun run lint:i18n
+```
+
+Run the repository-level checks required by any non-GUI files changed in the same work.

scripts/AGENTS.md

@@ -0,0 +1,27 @@
+# Script and release-tooling instructions
+
+This file applies to `scripts/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Safety boundary
+
+- `scripts/release.ts` is the release authority.
+- Release, publish, version-bump, deployment, and package-signing behavior is maintainer-controlled.
+- Never run `bun run release`, a publish command, or a deployment command unless the task explicitly requires the action and `MAINTAINERS.md` permits it.
+- Changes to release, packaging, dependency-installation, credential, or repository-automation scripts require explicit security review.
+
+## Implementation rules
+
+- Preserve Linux, macOS, and Windows behavior. Do not add shell-specific assumptions to cross-platform scripts.
+- Use explicit paths, deterministic inputs, bounded resource use, and actionable failures.
+- Use atomic replacement for files whose partial write would corrupt configuration, package metadata, release state, or recovery data.
+- Do not log secrets, tokens, request bodies, account identifiers, private paths, or personal data.
+- Do not weaken dry-run, exact-commit, CI-success, or explicit-confirmation gates.
+- Generated package assets must be produced by the owning preparation command, not edited manually.
+
+## Required validation
+
+- Run focused tests or probes for the changed script.
+- Run `bun run typecheck`.
+- Run `bun run privacy:scan` when the script handles configuration, credentials, requests, logs, or account data.
+- Run `bun run prepush` for release, packaging, dependency, or cross-platform tooling changes.
+- Report any platform-specific validation that was not executed.

src/AGENTS.md

@@ -0,0 +1,28 @@
+# Source runtime instructions
+
+This file applies to `src/` and inherits the repository-wide rules in `/AGENTS.md`.
+
+## Runtime and module rules
+
+- `src/` is Bun-native TypeScript in strict mode and uses ES modules only.
+- Do not assume a separate server compilation step.
+- Prefer Bun and Web-platform APIs. Introduce a Node-only runtime dependency only when the task explicitly requires compatibility code and the owning module already has that role.
+- Preserve existing public exports and configuration compatibility unless the task explicitly changes them.
+- Read the applicable documents in `structure/` before changing shared routing, adapters, transports, sidecars, authentication, configuration, or server architecture.
+
+## Implementation rules
+
+- Follow the existing subsystem boundaries and naming patterns.
+- Do not combine unrelated responsibilities to avoid creating another large shared module.
+- Handle asynchronous failures at request, transport, and sidecar boundaries. Optional integrations must degrade through the existing failure representation rather than crash the request path.
+- Provider catalog metadata belongs in the canonical provider registry and derivation flow. Do not duplicate provider facts across independent pickers or seeds.
+- Adapter changes must preserve the internal event contract, streaming behavior, tool calls, cancellation, error mapping, and image handling relevant to that adapter.
+- Authentication, OAuth, token, credential, management API, and CORS changes are security-boundary changes.
+
+## Tests and validation
+
+- Place focused regression coverage near the existing tests for the affected subsystem.
+- For focused behavior, run the relevant `bun test tests/<name>.test.ts` and `bun run typecheck`.
+- For shared routing, adapters, config, OAuth, or server behavior, also run `bun run test`.
+- For logging, requests, credentials, account data, or fixtures, also run `bun run privacy:scan`.
+- Update `docs-site/` when the change affects user-visible behavior or configuration.