ticket: use base32 project record ids

2026-06-09 22:10:47 +09:00
parent 0803bc3725
commit 4203988d74
798 changed files with 477 additions and 105 deletions
@@ -0,0 +1,33 @@
+---
+title: "Docs: document environment variable policy"
+state: "closed"
+created_at: "2026-05-31T08:26:46Z"
+updated_at: "2026-05-31T08:29:40Z"
+---
+
+## Background
+
+Environment variables are currently used for a few practical boundaries: XDG-style path discovery, runtime/socket directories, development overrides, and legacy/provider secret inputs. The user's preference is that this project should avoid environment variables where possible and make any remaining environment-variable surface explicit.
+
+A short investigation found that path resolution is mostly centralized in `manifest::paths`, while auth/web secret envs and test-only env mutation are more scattered. Normal runtime intentionally does not implicitly load `.env` files.
+
+## Requirements
+
+- Add current documentation for environment-variable policy and supported variables.
+- State the design preference clearly: avoid new environment variables when manifest/profile/config/typed secret references are better.
+- Document the currently supported categories:
+  - core path/resource discovery;
+  - runtime/socket/registry discovery;
+  - Pod runtime command development override;
+  - provider/WebSearch credential references;
+  - external compatibility variables such as Codex home;
+  - test/build/example-only environment variables.
+- Clarify that normal runtime must not implicitly load `.env` files.
+- Identify cleanup direction without implementing unrelated refactors in this ticket.
+
+## Acceptance criteria
+
+- A user/developer-facing docs page explains environment-variable policy and current variables.
+- Existing Nix/config docs link to the new policy page where relevant.
+- Documentation does not expose secret values or read ignored secret-like files.
+- `./tickets.sh doctor` and `git diff --check` pass.
@@ -0,0 +1,13 @@
+Documented the environment-variable policy and current supported surface.
+
+Implementation:
+- Added `docs/environment.md`.
+- Stated the preferred design rule: avoid new environment variables when profile/manifest/config/CLI/typed secret references are better.
+- Documented core path variables, runtime/socket variables, the Pod runtime command override, credential env references, external compatibility variables, and build/test/example-only variables.
+- Clarified that normal runtime does not implicitly load `.env` files.
+- Added cleanup direction for shared test env guards, keeping path resolution centralized, and moving toward typed secret references.
+- Linked the new page from `docs/nix.md` and installed it in the Nix package docs.
+
+Validation:
+- `./tickets.sh doctor`
+- `git diff --check`
@@ -0,0 +1,28 @@
+<!-- event: create author: tickets.sh at: 2026-05-31T08:26:46Z -->
+
+## Created
+
+Created by tickets.sh create.
+
+---
+
+<!-- event: close author: hare at: 2026-05-31T08:29:40Z status: closed -->
+
+## Closed
+
+Documented the environment-variable policy and current supported surface.
+
+Implementation:
+- Added `docs/environment.md`.
+- Stated the preferred design rule: avoid new environment variables when profile/manifest/config/CLI/typed secret references are better.
+- Documented core path variables, runtime/socket variables, the Pod runtime command override, credential env references, external compatibility variables, and build/test/example-only variables.
+- Clarified that normal runtime does not implicitly load `.env` files.
+- Added cleanup direction for shared test env guards, keeping path resolution centralized, and moving toward typed secret references.
+- Linked the new page from `docs/nix.md` and installed it in the Nix package docs.
+
+Validation:
+- `./tickets.sh doctor`
+- `git diff --check`
+
+
+---