@@ -0,0 +1,47 @@
+# Governance
+
+This is a one-page note so adopters know what to expect from this
+repository before they invest time on a PR.
+
+## Maintainer
+
+api-log has a single maintainer (`@2nd1st`). It is a hobby project
+plus a working tool for my own LLM-gateway recording needs — not a
+backed product, not a company deliverable. There is no SLA, no
+guaranteed response time, and no roadmap-voting process.
+
+## Decision-making
+
+- The maintainer's call is final on scope, design, and what ships.
+- Pull requests are welcome but acceptance is not guaranteed. Issues
+  that include a concrete adopter use case have a much higher chance
+  of becoming a feature; "wouldn't it be nice" requests do not.
+- For anything beyond a small fix, **open an issue with the use case
+  first**. A 200-line PR that gets closed is more friction than a
+  five-line issue that gets a "yes, send it" reply. This is the
+  gate-before-feature stance the project runs on.
+
+## License + forking
+
+- MIT license, no Contributor License Agreement.
+- Forking is fine and explicitly OK — if a feature is out of scope
+  here, your fork is the right home. The project's
+  [§"What we will not do"][wnwd] section is honest about hard limits
+  (no gateway features, no SDK instrumentation, no semantic
+  interpretation of captured content, no credential-value matching);
+  if you need any of those, a fork or a downstream tool is the
+  expected path, not a PR against this repo.
+
+## Code of conduct
+
+Contributors are expected to follow the project's
+[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) (Contributor Covenant
+v2.1). Report issues by opening a GitHub issue and mentioning the
+maintainer.
+
+## Security
+
+Security issues should follow the process in [SECURITY.md](../SECURITY.md).
+Do not file public issues for vulnerabilities.
+
+[wnwd]: ../ROADMAP.md#what-we-will-not-do
@@ -0,0 +1,87 @@
+---
+name: Bug report
+about: Capture path, read API, viewer, or plugin behaving incorrectly.
+title: ""
+labels: bug
+assignees: ""
+---
+
+<!--
+Before filing: search existing issues. Best-effort maintenance, one
+contributor, no SLA. A report with the fields below filled in moves
+much faster than a report without them.
+
+Redact bearer tokens / API keys before pasting JSONL or logs. The
+capture path stores them unredacted on disk (this is documented; see
+SECURITY.md) but they do not belong in a public issue.
+-->
+
+## Version
+
+```
+$ api-log -version
+# paste output
+```
+
+If running from `main`, paste the commit SHA (`git rev-parse HEAD`).
+
+## Deployment shape
+
+- Install method: Docker Compose / native binary / `go install` / built from source
+- OS + arch: e.g. `linux/amd64`, `darwin/arm64`
+- Upstream gateway in front of which api-log is deployed (sub2api / CPA / new-api / other / none)
+- Reverse proxy in front of api-log, if any (Caddy / nginx / none)
+
+## Steps to reproduce
+
+1. ...
+2. ...
+3. ...
+
+**Expected:** what should have happened.
+
+**Actual:** what did happen.
+
+If the bug involves a specific HTTP request, paste the request shape
+(method, path, relevant headers with credentials redacted, body
+shape — not the literal body if it carries customer data).
+
+## `/healthz` output
+
+The counters and storage blocks are the maintainer's primary
+diagnostic anchor. Capture them at the time of the incident if you
+still can:
+
+```bash
+curl -s http://localhost:7862/healthz | jq '{counters, storage}'
+```
+
+```json
+# paste output here
+```
+
+## Sample JSONL line (if capture-related)
+
+If the bug is about what got recorded (missing fields, wrong shape,
+truncation, parse failure), paste one JSONL line that reproduces it.
+Redact `Authorization` / `x-api-key` / equivalent header values
+yourself before pasting.
+
+```json
+# paste here
+```
+
+## Logs around the incident
+
+stderr from the api-log process (or `docker logs` / `journalctl -u
+api-log`) covering ~30 seconds before and after the incident.
+
+```
+# paste here
+```
+
+## Anything else
+
+Plugin config in effect (`config.yaml` plugins block + any
+`PUT /api/config/plugins` overrides), retention settings, anything
+non-default that might be relevant.
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/2nd1st/api-log/security/advisories/new
+    about: Do not file a public issue. Open a private security advisory.
+  - name: Contributing guide
+    url: https://github.com/2nd1st/api-log/blob/main/CONTRIBUTING.md
+    about: Scope, gate-before-feature stance, and the pre-PR command set live here.
+  - name: Read the docs first
+    url: https://github.com/2nd1st/api-log#readme
+    about: README, ARCHITECTURE.md, ROADMAP.md, and SECURITY.md cover most questions before they need to be asked.
@@ -0,0 +1,62 @@
+---
+name: Feature request
+about: Propose a change to the core proxy, read API, or shipped plugins.
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+<!--
+api-log is deliberately small. The "What we will not do" section of
+ROADMAP.md lists the categories of work that will be closed on sight:
+no gateway features (auth / routing / retries / rate limiting / caching
+/ rewriting), no SDK instrumentation, no semantic interpretation of
+recorded content, no automatic redaction in the capture path, no
+matching on credential-carrying header values.
+
+The default answer for new behavior is "off-by-default plugin", not
+"core change". If you have not read ROADMAP.md, do that first.
+
+Requests phrased as "wouldn't it be nice if api-log could..." will be
+closed. Requests grounded in an adopter use case the maintainer can
+reason about will be considered.
+-->
+
+## Adopter use case
+
+Concrete situation in your own deployment that this would address.
+Which gateway, what kind of traffic, what you are trying to learn or
+do that you cannot do today. Numbers help (trace volume, request
+shape, time horizon).
+
+## Why this cannot be a plugin
+
+api-log ships a plugin surface (`text-replace`, `text-append`,
+`path-filter`, `capture-filter`) and the surface is intentionally
+extensible. Before proposing a core change, explain why an
+off-by-default plugin — yours, in a fork or sidecar repo — cannot
+deliver the same outcome.
+
+## Existing surface that comes close
+
+What in api-log today (read API endpoint, JSONL field, plugin, env
+knob) gets partway to your use case? What is the gap?
+
+Link the relevant section of ARCHITECTURE.md or README.md.
+
+## Acceptable scope
+
+To bound review, name what is **in** scope and what is explicitly
+**out** of scope for the proposed change.
+
+- **In scope:** ...
+- **Out of scope:** ...
+
+A request that does not bound itself tends to grow during
+discussion. Bound it up front.
+
+## Alternatives considered
+
+Other ways you considered solving this (downstream tooling over the
+JSONL, a sidecar over `data/`, a change to the upstream gateway
+instead, etc.) and why the proposal here is the one you landed on.
@@ -0,0 +1,60 @@
+<!--
+api-log is best-effort, one contributor, no SLA. PRs that fill in the
+boxes below land faster than PRs that do not.
+
+If this PR changes the JSONL line shape, the on-disk layout, or the
+HTTP read API contract: read PHILOSOPHY.md § principle 6 first.
+Wire-format contracts follow append-only / new-format-key migration
+discipline; field renames and removals do not land.
+
+If this PR adds capture-path behavior, plugin scope, or anything
+that touches what gets recorded: read ROADMAP.md § "What we will
+not do" first.
+-->
+
+## What changed + why
+
+One paragraph. The "why" matters more than a file-by-file recap of
+the "what" — the diff already shows the what.
+
+## Trade-off chosen
+
+Name the alternative you considered and rejected, and the reason.
+"Did the obvious thing" is acceptable for small changes; for
+anything touching the capture path, read API, plugin surface, or
+on-disk format, name the alternative explicitly.
+
+## Tests
+
+- [ ] Added unit / integration tests covering the change.
+- [ ] No tests added — reason: <!-- e.g. docs-only, mechanical refactor with existing coverage -->
+
+## Local checks
+
+- [ ] `go test -race ./...` clean.
+- [ ] `golangci-lint run` clean (v2 config).
+- [ ] Integration harness `./tests/integration/run.sh` clean (if the change touches the proxy / read API / plugin path).
+
+## CHANGELOG
+
+- [ ] Added an entry under `## [Unreleased]` in `CHANGELOG.md`.
+- [ ] No CHANGELOG entry — reason: <!-- e.g. internal-only refactor, test-only change, docs typo -->
+
+If yes, paste the entry you added:
+
+```
+### Added / Changed / Fixed / Removed
+- ...
+```
+
+## Docs
+
+- [ ] `README.md` / `README.zh.md` touched if user-visible surface changed.
+- [ ] `ARCHITECTURE.md` touched if on-disk format, read API contract, or write path changed.
+- [ ] `ROADMAP.md` touched if this lands a tracked item or moves the "deferred" list.
+- [ ] `SECURITY.md` touched if the threat model or operator responsibilities changed.
+- [ ] No docs change needed.
+
+## Linked issue
+
+Closes #<!-- number --> <!-- or "n/a" with a one-line reason -->
@@ -1205,3 +1205,70 @@ buffer-then-expose machinery only when at least one registered plugin
 opts in via the new interface. Re-open Phase D when a real adopter
 files an issue with a concrete use case that BEFORE-tools-array,
 `ActionIntercept`, or Observer-scrub genuinely cannot serve.
+
+---
+
+## 14. What this is not
+
+The shape of the project is as much defined by what it refuses to
+do as by what it does. The points below are architectural, not
+roadmap items — they will not change without a §1-level
+amendment.
+
+### 14.1 Single-node only
+
+One binary, one `<data_dir>`. There is no clustering layer, no
+shared-storage replication, no leader election, no cross-node
+trace ID coordination. Two binaries pointed at the same data
+directory will collide at the ULID-generation and SQLite-writer
+layers; see [docs/operations.md](./docs/operations.md)
+"Multi-instance" for the failure modes.
+
+Horizontal capture scale is solved by running independent
+instances — one per LLM gateway upstream, each with its own data
+directory — and aggregating downstream from the JSONL trees. The
+project is shaped for the "tcpdump in front of one gateway"
+deployment; a multi-tenant control plane is out of scope.
+
+### 14.2 JSONL is truth; SQLite is rebuildable cache
+
+§1 states the invariant; this section restates it as a posture.
+Adopters can delete `index.sqlite` at any time and the binary will
+rebuild it from the JSONL tree on next startup. Backup strategies
+treat the JSONL tree as the only artifact that matters; the SQLite
+index is a query-acceleration convenience, not a second source of
+record.
+
+The forward-referenced `api-log rebuild` subcommand (ROADMAP
+"Day-2 operations") will surface this as an explicit operator
+command rather than the implicit startup-on-empty-data-dir
+behavior, but the underlying invariant is unchanged.
+
+### 14.3 WAL means concurrent readers, single writer
+
+The SQLite WAL mode documented in §4 buys us many concurrent
+readers (the read API, plus any external `sqlite3` session a human
+or a tool opens against the file) coexisting with the
+writer goroutine. It does **not** buy us multiple writers. The
+write path is one goroutine, full stop; the channel in front of it
+absorbs bursts and drops with a counter when it saturates (§7.3).
+Adopters writing custom tooling against `index.sqlite` should open
+read-only connections.
+
+### 14.4 No gateway behavior in the capture path
+
+A consolidated restatement of the ROADMAP "What we will not do"
+list as it intersects this document: the proxy does not
+authenticate, route, retry, rate-limit, cache, rewrite, or
+redact in the capture path. The `req.headers` and `resp.headers`
+captured in the JSONL line are what the proxy actually forwarded
+(modulo the §10.4 `X-Forwarded-*` suppression and the standard
+hop-by-hop strip ReverseProxy already performs). Plugins
+(§6.7 / ROADMAP §11) are the only sanctioned mechanism for
+operator-side mutation, and they are off by default.
+
+---
+
+Operator-facing material — backup procedure, manual WAL checkpoint
+one-liner, retention cross-reference, multi-instance behavior — is
+not in this document. See [docs/operations.md](./docs/operations.md).