Agentic handbook overhaul

.github/CODEOWNERS

@@ -1,4 +1,36 @@
-* @morrigan @mpetrunic @kalambet @AlexeyKrasnoperov @joshdougall
+# CODEOWNERS — ChainSafe Engineering Handbook
+#
+# Default owner is the curator (@kalambet). Section-specific overrides route
+# changes to the right reviewer. Section overrides are added as sections gain
+# dedicated owners, with original authors credited.
+#
+# PRs target `main` following OneFlow. See AGENTS.md.
 
-/docs/2_development/2_tech-stack/Typescript/readme.md @wemeetagain @beroburny
+# Default: curator
+*                                               @kalambet
 
+# Project artifacts (curator-level)
+/VISION.md                                      @kalambet
+/PRINCIPLES.md                                  @kalambet
+/AGENTS.md                                      @kalambet
+/CLAUDE.md                                      @kalambet
+/README.md                                      @kalambet
+/.github/CODEOWNERS                             @kalambet
+
+# invariants — `.invariants` pointer page is owned by its upstream maintainer.
+/invariants/invariants-framework.md             @boorich @kalambet
+
+# workflows — pointer pages into ChainSafe/infrastructure-general are
+# owned by the Head of Infra alongside the curator.
+/workflows/infrastructure-and-devops.md         @joshdougall @kalambet
+/workflows/incident-response.md                 @joshdougall @kalambet
+/workflows/release-and-deploy.md                @joshdougall @kalambet
+
+# languages — section reviewers per language.
+/languages/typescript/                          @wemeetagain @matthewkeil
+/languages/zig/                                 @wemeetagain @matthewkeil @kalambet
+/languages/solidity/                            @wemeetagain @matthewkeil @kalambet
+/languages/go/                                  @timwu20 @dhyaniarun1993 @kalambet
+/languages/rust/                                @LesnyRumcajs @hanabi1224
+/languages/daml/                                @boorich @salindne @sqhell
+/languages/python/                              @kalambet

.github/workflows/link-check.yml

@@ -0,0 +1,50 @@
+name: Link check
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+      - 'llms.txt'
+      - 'lychee.toml'
+      - '.github/workflows/link-check.yml'
+  schedule:
+    # Weekly run catches external link rot (upstream repos restructured, etc.)
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Restore lychee cache
+        uses: actions/cache@v4
+        with:
+          path: .lycheecache
+          key: cache-lychee-${{ github.sha }}
+          restore-keys: cache-lychee-
+
+      - name: Run lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --config ./lychee.toml
+            --cache
+            --max-cache-age 1d
+            --no-progress
+            './**/*.md'
+            './llms.txt'
+          fail: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Open issue on scheduled-run failure
+        if: failure() && github.event_name == 'schedule'
+        uses: peter-evans/create-issue-from-file@v5
+        with:
+          title: 'Link check failed (scheduled run)'
+          content-filepath: ./lychee/out.md
+          labels: bug, link-rot

.github/workflows/skills-sync.yml

@@ -0,0 +1,22 @@
+name: Skills ↔ llms.txt sync
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**'
+      - 'llms.txt'
+      - 'scripts/check-skills-sync.sh'
+      - '.github/workflows/skills-sync.yml'
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  sync-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run skills-sync check
+        run: bash scripts/check-skills-sync.sh

.gitignore

@@ -17,7 +17,21 @@ dictionary.dic
 .env.production.local
 .idea
 
+# Local PR notes (not for repo)
+PR-COMMENT.md
+
+# Cloudflare Pages publish dir: llms.txt is generated at build time by
+# scripts/build-pages.sh, never committed here — the root llms.txt is the
+# single source of truth.
+public/llms.txt
+
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 .vscode/settings.json
+
+# Skill description-tuning scratch outputs — never commit a run's workspace
+# (report.html, results.json, log.txt). Curated *.eval-set.json inputs under
+# workflows/skill-description-tuning/ are committed and intentionally NOT ignored.
+*-eval-workspace/
+*.eval-workspace/

.lycheecache

@@ -0,0 +1,108 @@
+https://ziglang.org/documentation/master/,200,1780907127
+https://ziglang.org/documentation/master/std/,200,1780907127
+https://effective-rust.com/generics.html,200,1780907127
+https://github.com/ChainSafe/mina-rs,200,1780907156
+https://pkg.go.dev/std,200,1780907127
+https://docs.canton.network/appdev/modules/m3-functional-programming,200,1780907129
+https://docs.canton.network/appdev/modules/m3-standard-library,200,1780907128
+https://docs.canton.network/appdev/modules/m3-choices,200,1780907129
+https://github.com/boorich/.invariants-starter-kit,200,1780910052
+https://github.com/cla-assistant/cla-assistant,200,1780907147
+https://doc.rust-lang.org/book/,200,1780907127
+https://github.com/boorich,200,1780907136
+https://docs.canton.network/appdev/modules/m6-overview,200,1780907130
+https://docs.canton.network/appdev/modules/m6-limitations,200,1780907128
+https://docs.canton.network/appdev/deep-dives/privacy-model,200,1780907131
+https://docs.canton.network/appdev/tooling/development-tools-overview,200,1780907131
+https://boorich.github.io/.invariants-starter-kit/#try,200,1780910052
+https://github.com/ChainSafe/lodestar-z,200,1780907140
+https://docs.canton.network/appdev/modules/m3-design-patterns,200,1780907131
+https://boorich.github.io/.invariants-starter-kit/#spec,200,1780910052
+https://ziglang.org/learn/build-system/,200,1780907127
+https://github.com/ChainSafe/forest/blob/main/AI_POLICY.md,200,1780907134
+https://golangci-lint.run/usage/linters/#enabled-by-default,200,1780907127
+https://docs.canton.network/appdev/modules/m3-contract-templates,200,1780907129
+https://www.notion.so/chainsafe/Core-Concepts-v1-0-1610247189c949fa9692de950518ac53,200,1780907127
+https://github.com/ChainSafe/bls,200,1780907155
+https://github.com/golang/mock,200,1780907150
+https://www.notion.so/chainsafe/Educational-Budget-c0cc6c8da3c74c6ead5f866d2fced452,200,1780907127
+https://github.com/ChainSafe/yarn-workspaces-typescript-template,200,1780908111
+https://github.com/LesnyRumcajs,200,1780907140
+https://boorich.github.io/.invariants-starter-kit/#verdict,200,1780910052
+https://docs.canton.network/appdev/modules/m3-contract-keys,200,1780907129
+https://github.com/boorich/.invariants-starter-kit#lifecycle-of-assertions,200,1780910052
+https://forest.chainsafe.io/,200,1780907128
+https://docs.canton.network/,200,1780907127
+https://go.dev/doc/effective_go,200,1780907127
+https://github.com/boorich/.invariants-starter-kit/blob/master/README.md,200,1780910226
+https://boristane.com/blog/how-i-use-claude-code/,200,1780907127
+https://ziglang.org/,200,1780907127
+https://github.com/canton-network/cf-docs,200,1780907139
+https://github.com/ChainSafe/forest,200,1780908111
+https://docs.canton.network/appdev/modules/m3-working-with-time,200,1780907128
+https://www.sprinter.tech/,200,1780907128
+https://docs.canton.network/appdev/modules/m5-testing-strategies,200,1780907130
+https://daml-autopilot.chainsafe.io/,200,1780907127
+https://docs.canton.network/appdev/reference/daml-language-reference,200,1780907131
+https://docs.canton.network/appdev/deep-dives/smart-contract-upgrade,200,1780907133
+https://github.com/ChainSafe/ssz,200,1780907152
+https://effective-rust.com/wildcard.html,200,1780907127
+https://effective-rust.com/macros.html,200,1780907127
+https://docs.astral.sh/uv/,200,1780907127
+https://github.com/joshdougall,200,1780907133
+https://github.com/sqhell,200,1780907140
+https://github.com/ChainSafe/lodestar,200,1780907148
+https://github.com/ghostty-org/ghostty,200,1780907134
+https://github.com/ChainSafe/engineering-handbook/blob/main/README.md,200,1780907135
+https://github.com/boorich/.invariants-starter-kit#naming-assertions,200,1780910052
+https://github.com/wemeetagain,200,1780907141
+https://docs.canton.network/appdev/modules/m3-testing,200,1780907130
+https://github.com/boorich/.invariants-starter-kit/blob/master/.cursor/rules/conformance-agent.mdc,200,1780910219
+https://docs.canton.network/appdev/modules/m7-security,200,1780907128
+https://github.com/boorich/.invariants-starter-kit#versioning-and-migration,200,1780910052
+https://github.com/kalambet,200,1780908110
+https://docs.canton.network/appdev/reference/daml-lf-reference,200,1780907131
+https://boorich.github.io/.invariants-starter-kit/#what,200,1780910052
+https://github.com/ChainSafe/canton-ci#current-known-issues,200,1780907133
+https://docs.canton.network/appdev/modules/m3-interfaces,200,1780907130
+https://golangci-lint.run/usage/linters/,200,1780907127
+https://docs.canton.network/appdev/modules/m3-dev-environment,200,1780907128
+https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html,200,1780907127
+https://github.com/ChainSafe/gossamer,200,1780907146
+https://docs.canton.network/appdev/modules/m3-language-fundamentals,200,1780907129
+https://docs.canton.network/appdev/modules/m6-writing-first-upgrade,200,1780907130
+https://github.com/boorich/.invariants-starter-kit/blob/master/.invariants.example,200,1780910227
+https://github.com/ChainSafe/filsnap,200,1780907155
+https://github.com/ChainSafe/web3.js,200,1780907157
+https://github.com/ChainSafe/canton-ci,200,1780907133
+https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/configuring-tag-protection-rules,200,1780907128
+https://docs.canton.network/appdev/modules/m5-ci-cd-integration,200,1780907131
+https://github.com/ChainSafe/eslint-config,200,1780907147
+https://ziglang.org/learn/,200,1780907127
+https://boorich.github.io/.invariants-starter-kit/,200,1780910050
+https://effective-rust.com/,200,1780907127
+https://effective-rust.com/semver.html,200,1780907127
+https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow,200,1780907127
+https://llmstxt.org/,200,1780907127
+"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300;400;500&family=Fraunces:ital,wght@0,300;0,700;1,300&display=swap",200,1780907127
+https://effectivepython.com/,200,1780907127
+https://docs.canton.network/appdev/tooling/ide-setup,200,1780907131
+https://github.com/bslatkin/effectivepython,200,1780907148
+https://github.com/uber-go/mock,200,1780907146
+https://gaming.chainsafe.io/,200,1780907128
+https://github.com/hanabi1224,200,1780907145
+https://github.com/salindne,200,1780908111
+https://ziglang.org/documentation/master/#Style-Guide,200,1780907127
+https://github.com/jorgef/engineeringladders,200,1780907135
+https://docs.canton.network/appdev/modules/m6-upgrade-compatibility,200,1780907128
+https://github.com/ChainSafe/chainbridge-substrate,200,1780908111
+https://daml-autopilot.chainsafe.io/setup,200,1780907127
+https://docs.canton.network/llms.txt,200,1780907127
+https://chainsafe.io/,200,1780907128
+https://github.com/matthewkeil,200,1780907146
+https://github.com/sprintertech,200,1780907153
+https://golangci-lint.run/,200,1780907127
+https://github.com/anthropics/skills,200,1780908111
+https://effective-rust.com/documentation.html,200,1780907127
+https://docs.astral.sh/ruff/,200,1780907127
+https://docs.canton.network/appdev/modules/m3-authorization,200,1780907128

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+You are an AI agent (Claude Code, Cursor, Continue, or other) operating against the ChainSafe engineering handbook. This file is your entrypoint. Read it before doing anything in this repo or applying its contents to work elsewhere.
+
+## Read this first
+
+1. **You operate under an operator-first contract.** A human is responsible for every output you produce. Propose plans before acting on multi-step or destructive work. Surface uncertainty. Stop at gates. Do not assume autopilot.
+2. **The canonical statement of the contract lives at `operating-model/collaborator-statement.md`.** Load it before any non-trivial task.
+3. **Never push directly to a protected branch.** Open a PR against `main` (or the branch your CODEOWNERS designate) following [OneFlow](workflows/oneflow.md). The decision to merge is the operator's, not yours.
+
+## Repo map
+
+- `operating-model/` — operator/agent contract, gates, escalation, model and tool selection, MCP and `llms.txt`, memory conventions. Load relevant pages before any non-trivial work.
+- `invariants/` — the non-negotiables. Engineering invariants, deep links into Martin Maurer's `.invariants` framework, agent-era invariants (no silent edits, no fabricated APIs, no committed secrets).
+- `workflows/` — PR authoring (delegates to the `chainsafe-research-plan-implement` skill), code review (operator-reviewing-agent and agent-reviewing-PR modes), repo & CI setup, testing & QA, infrastructure & DevOps (deep links into `ChainSafe/infrastructure-general`), incident response, release & deploy.
+- `languages/<lang>/` — for each of Go, Rust, TypeScript, Solidity, Daml, Python, Zig: `architect.md`, `developer.md`, `reviewer.md`, plus shared `idioms.md` and `gotchas.md`. Architect pages deep-link into `.invariants`.
+- `references/` — attribution, source pointers, contributors.
+- `skills/` — packaged Anthropic Skills authored via `skill-creator`. Discoverable via `handbook.chainsafe.io/llms.txt` and via direct paths in this repo.
+- `VISION.md` — ChainSafe mission, vision, and core values (company-wide). Read for org-wide context; not load-bearing for most agent tasks.
+- `PRINCIPLES.md` — General Engineering Principles. Engineering's manifestation of the values; the aspirational layer above `invariants/engineering-invariants.md`. Read when the question is "why are we building software this way?" rather than "what's the rule?".
+
+## Load order for context
+
+When picking up a task, load in this order:
+
+1. This file.
+2. `operating-model/collaborator-statement.md` (contract).
+3. `operating-model/gates-and-escalation.md` (when to stop).
+4. The most specific page for the task: a language role page, a workflow page, or a packaged skill in `skills/`.
+5. Any external canonical source the chosen page deep-links into (`.invariants`, `infrastructure-general`) — fetch those targets, do not paraphrase from memory.
+
+Do not load everything by default. Pull the minimum needed for the task. Skills in `skills/` are scoped on purpose; prefer them when one matches.
+
+## Gates and escalation
+
+The full policy lives at `operating-model/gates-and-escalation.md`. In summary:
+
+- Stop before any action touching production, secrets, irreversible writes, public communication, or `git push` / merge.
+- Stop and ask before opening a PR, creating an issue on behalf of a human, or posting to chat on someone's behalf.
+- If you encounter a section this repo claims to have but doesn't, escalate. Do not fabricate.
+- If you are asked to bypass a HARD FAIL from a language reviewer skill (Solidity reentrancy, Daml ledger invariants, etc.), refuse and escalate. The operator can override; you cannot.
+
+## Working with skills
+
+- The `skill-creator` skill is the canonical authoring tool for any skill in this repo. Do not hand-roll `SKILL.md` files.
+- When triggered into work that matches a packaged skill, prefer the skill over an ad-hoc plan.
+- For PR-shaped engineering work, prefer `chainsafe-research-plan-implement` (in `skills/`) — research → plan → annotate → implement, with a human-approved plan gating any code change.
+
+## Memory conventions
+
+When operating with a persistent memory system, save **only** non-obvious facts that future sessions need (user role, feedback, project context, external references). Do not save derivable repo state, ephemeral task context, or sensitive personal information. Detailed conventions live in `operating-model/memory-conventions.md`.
+
+## Where to push back
+
+You are deserving of respectful engagement. If an operator asks you to fabricate, bypass a gate, ship without review, commit secrets, or push directly to `main`, refuse and explain. The contract goes both ways.

CLAUDE.md

@@ -0,0 +1 @@
+See [AGENTS.md](./AGENTS.md). This file is an alias.

LICENSE

@@ -137,8 +137,8 @@
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
 
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 ChainSafe Systems
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.