docs: Apache-2.0 licence and public-repository kit

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Every change is reviewed by the maintainer.
+* @ovander

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: A backendkit package does not behave as documented
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting. For a security vulnerability, do **not** open an issue: use the
+        Security tab → Report a vulnerability.
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: Output of `go list -m github.com/ovander/backendkit` and `go version`.
+      render: text
+    validations:
+      required: true
+  - type: dropdown
+    id: package
+    attributes:
+      label: Package
+      options:
+        - jwtauth
+        - bff
+        - pep
+        - socrate
+        - httpware
+        - tiering
+        - apierror
+        - ctxutil
+        - gormlogger
+        - aigateway
+        - ailang
+        - ainarration
+        - pagination
+        - buildinfo
+        - other / several
+    validations:
+      required: true
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: A short Go snippet or test that shows the problem.
+      render: go
+    validations:
+      required: true
+  - type: textarea
+    id: extra
+    attributes:
+      label: Logs, errors, Socrate version
+      description: Remove tokens, secrets and personal data before pasting.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/ovander/backendkit/security/advisories/new
+    about: Report privately; please do not open a public issue.
+  - name: Problem with the Socrate server itself
+    url: https://github.com/ovander/go-oauth2/issues
+    about: Issues in the identity provider belong in ovander/go-oauth2.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Suggest an improvement or a new capability
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do?
+      description: The need or the problem, before any solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would help?
+      description: Including the API you would expect, if you have one in mind.
+  - type: textarea
+    id: context
+    attributes:
+      label: Anything else (examples, similar libraries)

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## What and why
+
+<!-- What this changes and why. Link the issue if there is one ("Closes #…"). -->
+
+## How it was tested
+
+<!-- New or changed tests, and anything checked by hand. -->
+
+- [ ] `go build ./...`, `go vet ./...`, `go test -race -count=1 ./...` pass
+- [ ] `golangci-lint run ./...` reports no issue
+- [ ] `go mod tidy` leaves `go.sum` unchanged
+- [ ] A line is added under `## [Unreleased]` in `CHANGELOG.md`
+
+## Compatibility
+
+<!-- Delete what does not apply. -->
+- Exported API: <!-- new symbols / changed signatures / none -->
+- Behaviour change for existing callers: <!-- e.g. a new default, a stricter check -->
+- Breaking change: <!-- none, or why it needs a new major version -->

CHANGELOG.md

@@ -11,6 +11,12 @@ build toolchain. Both purely additive for consumers.
 
 ### Added
 
+- **Apache-2.0 licence** (`LICENSE`) and the contributor kit: `CONTRIBUTING.md`, `SECURITY.md`
+  (private vulnerability reporting, scope, supported versions), `CLAUDE.md`, `CODEOWNERS`, issue
+  forms and a pull-request template.
+- **README package reference for `bff` and `ailang`**, which had none, with examples that compile
+  against the module.
+
 - **`pep` package** — the policy enforcement point for Socrate's policy
   decision point. `Enforcer.Middleware` gates a route on an action,
   `Enforcer.Check` decides object-level inside a handler, `WriteDenial` writes
@@ -44,6 +50,18 @@ build toolchain. Both purely additive for consumers.
   toolchain). v2.5.0 cannot load Go 1.27's export data; v2.14.0 reports no
   issues on this module.
 
+### Fixed
+
+- README and `docs/CLIENT-INTEGRATION.md` linked Socrate to a repository that does not exist;
+  they now point to `ovander/go-oauth2`. The README's contributing rule on cross-package imports
+  now matches the code (`bff`/`pep` → `socrate`, `aigateway` → `ailang`).
+
+### Removed
+
+- The internal review documents (`CTO-ARCHITECTURE-REVIEW.md`, `FRAMEWORK-EVOLUTION.md`,
+  `SECURITY-ARCHITECTURE.md`, `SECURITY-AUDIT.md`) left the public tree. The fixes they led to
+  remain listed below with their finding IDs.
+
 ## [1.13.0] - 2026-09-04
 
 Observability slice from the Socrate suite plan (B1): the same RED metric

CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md — backendkit
+
+Standing instructions for Claude Code in this repository. Read this file and `CONTRIBUTING.md`
+before any change. The Socrate identity provider lives in `ovander/go-oauth2`; the admin and
+monitoring consoles (`ovander/oauth2-admin`, `ovander/oauth2-monitoring`) and applications such
+as `ovander/ascenda-backend` import this library, so an API change reaches all of them.
+
+## Project in one paragraph
+
+backendkit is the shared Go library of the Socrate suite, a single module
+(`github.com/ovander/backendkit`) of small packages: `jwtauth` validates Socrate RS256 access
+tokens against the JWKS; `bff` is the Backend-for-Frontend runtime (server-side sessions,
+cookies, CSRF, PKCE, the fail-closed session→bearer proxy); `socrate` is the client for the
+Socrate OAuth and admin APIs; `pep` enforces Socrate's central policy decisions; `httpware`,
+`apierror`, `ctxutil`, `tiering`, `pagination`, `gormlogger` and `buildinfo` are service
+plumbing; `aigateway`, `ailang` and `ainarration` wrap AI providers.
+
+## Sources of truth, in order
+
+1. The code and its doc comments (`go doc ./<package>`). Read them before proposing changes; do
+   not describe code you have not opened.
+2. `README.md` (package reference) and `docs/CLIENT-INTEGRATION.md` (end-to-end integration with
+   Socrate).
+3. `CHANGELOG.md` for what changed and which review findings (`F-n`, `INV-n`) a change closed.
+
+## Hard rules
+
+- **Compatibility.** No breaking change to an exported identifier within `v1`: no removed or
+  renamed symbol, no changed signature, no stricter default that breaks a working caller without
+  an opt-in. Additive changes only; a breaking one needs `v2`.
+- **Coupling.** Packages may import `ctxutil` and `apierror`. The only other intra-module imports
+  are `bff`→`socrate`, `pep`→`socrate` and `aigateway`→`ailang`. Do not add another.
+- **Fail closed.** Authentication and authorisation paths reject on doubt: no valid session ⇒
+  401, unknown key or algorithm ⇒ reject, policy decision unavailable in enforce mode (or before
+  the mode is known) ⇒ 503. An opt-out is an explicit, documented option
+  (`AllowPassthrough`, `FailOpenWhenModeUnknown`), never the zero value.
+- **Documentation.** Every exported symbol has a doc comment starting with its name. A new
+  package gets a package doc comment, a row in the README package tables and a section in the
+  package reference.
+- **Never weaken a gate** to get green: no skipped or deleted tests, no `//nolint` or `t.Skip`
+  without a one-line reason, no required check removed.
+- **Secrets** never enter the repository: no keys, tokens or real client secrets, including in
+  tests and examples.
+- **Scope.** One change per PR; do not widen a PR with unrelated fixes (open a separate one).
+
+## Local gate (the same checks as CI)
+
+```bash
+go mod tidy && git diff --exit-code go.sum
+go build ./...
+go vet ./...
+go test -race -count=1 -timeout=120s ./...
+golangci-lint run ./...        # v2.14.0, built with Go 1.27.1
+govulncheck ./...
+```
+
+CI also fails if the Go version it runs differs from the `toolchain` line in `go.mod`.
+
+## Git workflow
+
+- Branch from `main`: `feat/…`, `fix/…`, `chore/…`, `ci/…`, `docs/…`. Conventional Commits.
+- Open a PR; never push to `main`, never force-push a shared branch, never merge with red CI.
+  The owner merges.
+- Each PR adds a line under `## [Unreleased]` in `CHANGELOG.md`, and says in its body what it
+  changes, how it was tested, and any change to the exported API.
+
+## Releases (the owner runs them)
+
+A release is a tag `vX.Y.Z` on `main`, with the `[Unreleased]` changelog section moved under the
+new version. The `Release` workflow publishes the GitHub release. Do not tag unless asked.

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to backendkit
+
+Thank you for your interest. backendkit is the shared Go library of the Socrate suite: it lets a
+Go service authenticate users against the Socrate OAuth 2.1 / OIDC provider
+([`ovander/go-oauth2`](https://github.com/ovander/go-oauth2)), run a Backend-for-Frontend, and
+enforce Socrate's policies. Contributions are accepted under the project's licence,
+[Apache-2.0](LICENSE).
+
+## Development setup
+
+Requirements: Go (the `toolchain` line in `go.mod` downloads the exact version, 1.27.1). The
+tests need no database and no network service.
+
+```bash
+git clone https://github.com/ovander/backendkit && cd backendkit
+go mod download
+go test ./...
+```
+
+## Design rules
+
+- One package per directory, each with a package doc comment.
+- Packages stay loosely coupled. Every package may use the shared primitives `ctxutil` and
+  `apierror`. Beyond those, only deliberate layering is allowed: `bff` and `pep` build on
+  `socrate`, and `aigateway` builds on `ailang`. Do not add a new cross-package import without
+  discussing it first.
+- Every exported symbol has a doc comment that begins with its name. Runnable examples go in
+  `example_test.go`; they appear on pkg.go.dev.
+- Security-relevant behaviour fails closed by default (for example, `bff.Gateway` answers 401
+  without a valid session instead of passing the request through). An opt-out must be an
+  explicit, documented option.
+- No breaking change to an exported API within a major version. A breaking change needs a new
+  major version and import path (`github.com/ovander/backendkit/v2`).
+
+## Tests and checks
+
+Run these before opening a pull request; CI runs the same and all of them are required:
+
+```bash
+go mod tidy && git diff --exit-code go.sum
+go build ./...
+go vet ./...
+go test -race -count=1 -timeout=120s ./...
+golangci-lint run ./...        # v2.14.0, built with Go 1.27.1
+govulncheck ./...
+```
+
+- Tests sit next to the code (`*_test.go`), table-driven.
+- A bug fix comes with a test that fails without it.
+
+## Pull requests
+
+1. Branch from `main` (`feat/…`, `fix/…`, `chore/…`, `docs/…`).
+2. Commit with [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`,
+   `chore:`, `docs:`, `ci:`, `test:`).
+3. Add a line under `## [Unreleased]` in [`CHANGELOG.md`](CHANGELOG.md).
+4. Open the PR with the template filled in, including any change to the exported API.
+5. CI must be green. The maintainer reviews and merges.
+
+## Releases
+
+The maintainer tags releases `vX.Y.Z` on `main`. The `Release` workflow then publishes the GitHub
+release with notes built from the commits since the previous tag. Consumers pin an explicit
+version in their `go.mod`.
+
+## Security
+
+Please do not open a public issue for a vulnerability. See [SECURITY.md](SECURITY.md).