From a1035ef8270e824d5867c55381db2c012e6d1e5d Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:39:52 +0530
Subject: [PATCH 01/13] chore: add repository foundation

---
 .github/ISSUE_TEMPLATE/bug.yml    | 44 +++++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/config.yml |  5 ++++
 .github/ISSUE_TEMPLATE/rfc.yml    | 44 +++++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/task.yml   | 44 +++++++++++++++++++++++++++++++
 .github/PULL_REQUEST_TEMPLATE.md  | 20 ++++++++++++++
 .github/workflows/guardrails.yml  | 21 +++++++++++++++
 CONTRIBUTING.md                   | 42 +++++++++++++++++++++++++++++
 LICENSES.md                       |  8 ++++++
 README.md                         | 10 +++++++
 SECURITY.md                       |  9 +++++++
 hk.pkl                            | 23 ++++++++++++++++
 mise.toml                         | 29 ++++++++++++++++++++
 renovate.json                     |  7 +++++
 13 files changed, 306 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug.yml
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/rfc.yml
 create mode 100644 .github/ISSUE_TEMPLATE/task.yml
 create mode 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/workflows/guardrails.yml
 create mode 100644 CONTRIBUTING.md
 create mode 100644 LICENSES.md
 create mode 100644 SECURITY.md
 create mode 100644 hk.pkl
 create mode 100644 mise.toml
 create mode 100644 renovate.json

diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
new file mode 100644
index 0000000..4cc977f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -0,0 +1,44 @@
+name: Bug report
+description: Report behavior that is broken, incorrect, or unexpectedly failing.
+title: "fix: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for reproducible defects. Keep secrets, real local session data, and private logs out of public issues.
+  - type: textarea
+    id: current-behavior
+    attributes:
+      label: Current behavior
+      description: What happens now?
+    validations:
+      required: true
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected behavior
+      description: What should happen instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Minimal steps a maintainer can run to reproduce the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, runtime versions, branch/commit, and affected package or command.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the bug is fixed.
+    validations:
+      required: false
+
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..a00c3f0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Private security report
+    url: https://github.com/agent-trail/web/security/advisories/new
+    about: Report vulnerabilities privately instead of opening a public issue.
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
new file mode 100644
index 0000000..c50a6b4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -0,0 +1,44 @@
+name: RFC / spec decision
+description: Propose a load-bearing Agent Trail format, schema, validation, package layout, or architecture decision.
+title: "rfc: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this before changing load-bearing shape such as normative format or schema semantics, validation terminology or behavior, versioning, hash semantics, artifact identity, package layout, durable architecture, or public URL shape.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or decision
+      description: What decision needs to be made, and why now?
+    validations:
+      required: true
+  - type: textarea
+    id: affected-surface
+    attributes:
+      label: Affected contract surface
+      description: Name the spec section, schema path, package API, CLI behavior, docs, ADRs, fixtures, or public URLs affected.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: State the exact rule or direction to adopt.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: List plausible options and tradeoffs.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the decision has been implemented.
+    validations:
+      required: true
+
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
new file mode 100644
index 0000000..8d19bdf
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -0,0 +1,44 @@
+name: Task or feature
+description: Request a scoped implementation task, feature, refactor, or docs update.
+title: "feat: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this for work that should be implementable by a human or coding agent from the issue alone.
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should be true when this is done?
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: What is included?
+    validations:
+      required: true
+  - type: textarea
+    id: non-goals
+    attributes:
+      label: Non-goals
+      description: What should not be changed or added?
+    validations:
+      required: false
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance criteria
+      description: Observable outcomes that prove the task is complete.
+    validations:
+      required: true
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification
+      description: Commands or checks that should pass.
+    validations:
+      required: true
+
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..e320561
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,20 @@
+## Summary
+
+- 
+
+## Public Impact
+
+- [ ] No public contract change
+- [ ] Spec or schema change
+- [ ] Public package API change
+- [ ] CLI behavior change
+- [ ] Public URL or docs behavior change
+
+## Verification
+
+- 
+
+## Reviewer Notes
+
+- 
+
diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
new file mode 100644
index 0000000..6971b75
--- /dev/null
+++ b/.github/workflows/guardrails.yml
@@ -0,0 +1,21 @@
+name: guardrails
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  guardrails:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@5228313ee0372e111a38da051671ca30fc5a96db # v3
+      - name: Run repository checks
+        run: mise run check
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..03233d5
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,42 @@
+# Contributing
+
+Agent Trail work is tracked in Linear and implemented through pull requests.
+
+## Workflow
+
+- Start from a Linear issue or accepted maintainer direction.
+- Keep changes scoped to the active issue.
+- Use Conventional Commit subjects for commits and pull request titles.
+- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
+- Do not commit real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
+
+## Local Setup
+
+Install tools and hooks:
+
+```sh
+mise install
+mise run hooks:install
+```
+
+Common tasks:
+
+```sh
+mise run check
+mise run lint
+mise run test
+```
+
+`mise` is the repo entrypoint for tools and tasks. `hk` owns Git hooks and project lint gates.
+
+## Pull Requests
+
+Before opening a pull request:
+
+- Run `mise run check`.
+- Link the Linear issue.
+- State public spec, schema, package API, CLI, or URL impact.
+- Include exact verification commands and results.
+
+Pull requests are squash-merged. Keep branches narrow and delete them after merge.
+
diff --git a/LICENSES.md b/LICENSES.md
new file mode 100644
index 0000000..68b543d
--- /dev/null
+++ b/LICENSES.md
@@ -0,0 +1,8 @@
+# Licensing
+
+This repository contains the Agent Trail docs site and shared trail web viewer.
+
+Unless otherwise noted, source code, site docs, tests, and implementation documentation in this repository are licensed under MIT.
+
+The Agent Trail format contract lives in `agent-trail/spec` and is Apache-2.0 unless that repository says otherwise.
+
diff --git a/README.md b/README.md
index 54a154a..b39c571 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,12 @@
 # web
 Agent Trail docs site and shared trail web viewer.
+
+## Development
+
+```sh
+mise install
+mise run hooks:install
+mise run check
+```
+
+See `CONTRIBUTING.md` for workflow and PR expectations.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..62c36f2
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,9 @@
+# Security
+
+Do not open public issues for vulnerabilities.
+
+Use GitHub private vulnerability reporting:
+
+https://github.com/agent-trail/web/security/advisories/new
+
+Do not include secrets, credentials, private local paths, or unredacted session data in reports unless they are necessary to reproduce the issue.
diff --git a/hk.pkl b/hk.pkl
new file mode 100644
index 0000000..b69058f
--- /dev/null
+++ b/hk.pkl
@@ -0,0 +1,23 @@
+amends "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Builtins.pkl"
+
+local linters = new Mapping {
+  ["actionlint"] = Builtins.actionlint
+  ["zizmor"] {
+    glob = List(".github/workflows/*.yml", ".github/workflows/*.yaml")
+    check = "zizmor .github/workflows"
+  }
+}
+
+hooks {
+  ["pre-commit"] {
+    steps = linters
+  }
+  ["pre-push"] {
+    steps = linters
+  }
+  ["check"] {
+    steps = linters
+  }
+}
+
diff --git a/mise.toml b/mise.toml
new file mode 100644
index 0000000..06b3c38
--- /dev/null
+++ b/mise.toml
@@ -0,0 +1,29 @@
+[tools]
+"aqua:jdx/hk" = "1.47.0"
+"aqua:rhysd/actionlint" = "1.7.12"
+"aqua:zizmorcore/zizmor" = "1.25.2"
+
+[tasks.setup]
+description = "Install tools and configure Git hooks"
+depends = ["hooks:install"]
+
+[tasks."hooks:install"]
+description = "Install hk Git hooks"
+run = "hk install"
+
+[tasks.check]
+description = "Run all repository checks"
+depends = ["lint", "test"]
+
+[tasks.lint]
+description = "Run project lint gates"
+run = "hk check"
+
+[tasks.test]
+description = "Run tests for this repository"
+run = "echo 'No tests configured yet.'"
+
+[tasks."check:actions"]
+description = "Validate GitHub Actions workflows"
+run = "actionlint && zizmor .github/workflows"
+
diff --git a/renovate.json b/renovate.json
new file mode 100644
index 0000000..057c514
--- /dev/null
+++ b/renovate.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "labels": ["dependencies"],
+  "timezone": "Asia/Kolkata"
+}
+

From 45127d6508162a864129d1dee03c2a9ee4df79bf Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:56:06 +0530
Subject: [PATCH 02/13] chore: address review feedback

---
 .github/PULL_REQUEST_TEMPLATE.md | 3 ++-
 .github/workflows/guardrails.yml | 4 ++++
 CONTRIBUTING.md                  | 4 +---
 README.md                        | 3 +--
 mise.toml                        | 3 +--
 renovate.json                    | 4 +---
 6 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e320561..656a954 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,3 +1,5 @@
+# Pull Request
+
 ## Summary
 
 - 
@@ -17,4 +19,3 @@
 ## Reviewer Notes
 
 - 
-
diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
index 6971b75..8e40a50 100644
--- a/.github/workflows/guardrails.yml
+++ b/.github/workflows/guardrails.yml
@@ -9,6 +9,10 @@ on:
 permissions:
   contents: read
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   guardrails:
     runs-on: ubuntu-latest
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03233d5..28d57b1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,8 +15,7 @@ Agent Trail work is tracked in Linear and implemented through pull requests.
 Install tools and hooks:
 
 ```sh
-mise install
-mise run hooks:install
+mise run setup
 ```
 
 Common tasks:
@@ -39,4 +38,3 @@ Before opening a pull request:
 - Include exact verification commands and results.
 
 Pull requests are squash-merged. Keep branches narrow and delete them after merge.
-
diff --git a/README.md b/README.md
index b39c571..bebc8fb 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,7 @@ Agent Trail docs site and shared trail web viewer.
 ## Development
 
 ```sh
-mise install
-mise run hooks:install
+mise run setup
 mise run check
 ```
 
diff --git a/mise.toml b/mise.toml
index 06b3c38..40da695 100644
--- a/mise.toml
+++ b/mise.toml
@@ -25,5 +25,4 @@ run = "echo 'No tests configured yet.'"
 
 [tasks."check:actions"]
 description = "Validate GitHub Actions workflows"
-run = "actionlint && zizmor .github/workflows"
-
+run = "if [ -d .github/workflows ]; then actionlint && zizmor .github/workflows; else echo 'No GitHub Actions workflows configured.'; fi"
diff --git a/renovate.json b/renovate.json
index 057c514..6dc7957 100644
--- a/renovate.json
+++ b/renovate.json
@@ -1,7 +1,5 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": ["config:recommended"],
-  "labels": ["dependencies"],
-  "timezone": "Asia/Kolkata"
+  "labels": ["dependencies"]
 }
-

From d84fe5483dcfe49682f3191168e607332d07ad9a Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 15:57:44 +0530
Subject: [PATCH 03/13] chore: normalize issue templates

---
 .github/ISSUE_TEMPLATE/bug.yml  | 1 -
 .github/ISSUE_TEMPLATE/rfc.yml  | 1 -
 .github/ISSUE_TEMPLATE/task.yml | 1 -
 3 files changed, 3 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
index 4cc977f..d102922 100644
--- a/.github/ISSUE_TEMPLATE/bug.yml
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -41,4 +41,3 @@ body:
       description: Observable outcomes that prove the bug is fixed.
     validations:
       required: false
-
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
index c50a6b4..9ea56e9 100644
--- a/.github/ISSUE_TEMPLATE/rfc.yml
+++ b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -41,4 +41,3 @@ body:
       description: Observable outcomes that prove the decision has been implemented.
     validations:
       required: true
-
diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml
index 8d19bdf..11725e0 100644
--- a/.github/ISSUE_TEMPLATE/task.yml
+++ b/.github/ISSUE_TEMPLATE/task.yml
@@ -41,4 +41,3 @@ body:
       description: Commands or checks that should pass.
     validations:
       required: true
-

From 4eda41082786e649d8d1b71e7c8a4dc9bcb279f9 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 16:14:16 +0530
Subject: [PATCH 04/13] docs: add agent instructions

---
 AGENTS.md | 24 ++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 25 insertions(+)
 create mode 100644 AGENTS.md
 create mode 120000 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6758a8d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# Agent Instructions
+
+This repo owns the Agent Trail website and web viewer surfaces.
+
+## Workflow
+
+- Start from the linked Linear issue or maintainer direction.
+- Keep changes scoped to web UI, viewer behavior, routing, docs pages, or web deployment.
+- Do not change the Agent Trail file format contract here; make spec changes in the spec repo.
+- Do not commit real local sessions, secrets, credentials, private logs, or unredacted user data.
+- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
+
+## Commands
+
+- Use `mise run setup` for local tool and hook setup.
+- Use `mise run check` before opening or updating a pull request.
+- Use `mise run check:actions` after editing GitHub Actions workflows.
+
+## Pull Requests
+
+- Use `.github/PULL_REQUEST_TEMPLATE.md`.
+- Link the Linear issue.
+- State web UI, viewer, URL, or docs impact.
+- Include exact verification commands and results.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file

From 9ee3a93971329e8dd5df410e639c006f27050857 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:22:30 +0530
Subject: [PATCH 05/13] docs: trim agent instructions

---
 AGENTS.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6758a8d..5aebb7d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,7 +8,6 @@ This repo owns the Agent Trail website and web viewer surfaces.
 - Keep changes scoped to web UI, viewer behavior, routing, docs pages, or web deployment.
 - Do not change the Agent Trail file format contract here; make spec changes in the spec repo.
 - Do not commit real local sessions, secrets, credentials, private logs, or unredacted user data.
-- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
 
 ## Commands
 

From 6fafc03f02bc141157fc516dc582578fd2d1da33 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:32:39 +0530
Subject: [PATCH 06/13] chore: pin bun runtime

---
 mise.toml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mise.toml b/mise.toml
index 40da695..78fd024 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,4 +1,5 @@
 [tools]
+bun = "1.2.17"
 "aqua:jdx/hk" = "1.47.0"
 "aqua:rhysd/actionlint" = "1.7.12"
 "aqua:zizmorcore/zizmor" = "1.25.2"

From bd9a4ee71de872b12529455f15771ac84e059c86 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:53:13 +0530
Subject: [PATCH 07/13] chore: update tool pins

---
 .github/workflows/guardrails.yml | 4 ++--
 hk.pkl                           | 5 ++---
 mise.toml                        | 4 ++--
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/guardrails.yml b/.github/workflows/guardrails.yml
index 8e40a50..a3487eb 100644
--- a/.github/workflows/guardrails.yml
+++ b/.github/workflows/guardrails.yml
@@ -17,9 +17,9 @@ jobs:
   guardrails:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
         with:
           persist-credentials: false
-      - uses: jdx/mise-action@5228313ee0372e111a38da051671ca30fc5a96db # v3
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
       - name: Run repository checks
         run: mise run check
diff --git a/hk.pkl b/hk.pkl
index b69058f..68e6af5 100644
--- a/hk.pkl
+++ b/hk.pkl
@@ -1,5 +1,5 @@
-amends "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Config.pkl"
-import "package://github.com/jdx/hk/releases/download/v1.47.0/hk@1.47.0#/Builtins.pkl"
+amends "package://github.com/jdx/hk/releases/download/v1.48.0/hk@1.48.0#/Config.pkl"
+import "package://github.com/jdx/hk/releases/download/v1.48.0/hk@1.48.0#/Builtins.pkl"
 
 local linters = new Mapping {
   ["actionlint"] = Builtins.actionlint
@@ -20,4 +20,3 @@ hooks {
     steps = linters
   }
 }
-
diff --git a/mise.toml b/mise.toml
index 78fd024..e8025ff 100644
--- a/mise.toml
+++ b/mise.toml
@@ -1,6 +1,6 @@
 [tools]
-bun = "1.2.17"
-"aqua:jdx/hk" = "1.47.0"
+bun = "1.3.14"
+"aqua:jdx/hk" = "1.48.0"
 "aqua:rhysd/actionlint" = "1.7.12"
 "aqua:zizmorcore/zizmor" = "1.25.2"
 

From 3861c4268398504395af5a835ea409a313c3310e Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 18:56:23 +0530
Subject: [PATCH 08/13] docs: clarify contributor guidance

---
 AGENTS.md       |  4 ++++
 CONTRIBUTING.md | 20 +++++++++++---------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5aebb7d..a12f80e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,10 @@ This repo owns the Agent Trail website and web viewer surfaces.
 - Use `mise run check` before opening or updating a pull request.
 - Use `mise run check:actions` after editing GitHub Actions workflows.
 
+## Dependencies and Tools
+
+- Before introducing a package, tool, or GitHub Action, check the latest upstream stable version and use it unless there is a documented reason not to.
+
 ## Pull Requests
 
 - Use `.github/PULL_REQUEST_TEMPLATE.md`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 28d57b1..66959b4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,14 +1,12 @@
 # Contributing
 
-Agent Trail work is tracked in Linear and implemented through pull requests.
+Thanks for helping improve Agent Trail.
 
-## Workflow
+## Before You Start
 
-- Start from a Linear issue or accepted maintainer direction.
-- Keep changes scoped to the active issue.
-- Use Conventional Commit subjects for commits and pull request titles.
-- Do not include agent attribution in commits, pull request bodies, generated docs, or code comments.
-- Do not commit real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
+- Open or pick up a Linear issue before starting larger changes.
+- Keep pull requests focused on one problem.
+- Avoid committing real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
 
 ## Local Setup
 
@@ -26,7 +24,11 @@ mise run lint
 mise run test
 ```
 
-`mise` is the repo entrypoint for tools and tasks. `hk` owns Git hooks and project lint gates.
+`mise` installs repo tools and runs tasks. `hk` owns local Git hooks.
+
+## Dependencies and Tools
+
+When adding a package, tool, or GitHub Action, check the latest stable upstream version first. Use the latest version by default; if you pin an older version, explain why in the pull request.
 
 ## Pull Requests
 
@@ -34,7 +36,7 @@ Before opening a pull request:
 
 - Run `mise run check`.
 - Link the Linear issue.
-- State public spec, schema, package API, CLI, or URL impact.
+- Summarize web UI, viewer, URL, or docs impact.
 - Include exact verification commands and results.
 
 Pull requests are squash-merged. Keep branches narrow and delete them after merge.

From 3619dc4644222f737ec85e876ca9282b00e6cf66 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 19:03:17 +0530
Subject: [PATCH 09/13] docs: add repo branding and license

---
 LICENSE     | 9 +++++++++
 LICENSES.md | 8 --------
 README.md   | 9 +++++++--
 3 files changed, 16 insertions(+), 10 deletions(-)
 create mode 100644 LICENSE
 delete mode 100644 LICENSES.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..700eaf7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Agent Trail contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/LICENSES.md b/LICENSES.md
deleted file mode 100644
index 68b543d..0000000
--- a/LICENSES.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Licensing
-
-This repository contains the Agent Trail docs site and shared trail web viewer.
-
-Unless otherwise noted, source code, site docs, tests, and implementation documentation in this repository are licensed under MIT.
-
-The Agent Trail format contract lives in `agent-trail/spec` and is Apache-2.0 unless that repository says otherwise.
-
diff --git a/README.md b/README.md
index bebc8fb..30da687 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
-# web
-Agent Trail docs site and shared trail web viewer.
+# Agent Trail Web
+
+Docs site and shared trail web viewer for Agent Trail.
 
 ## Development
 
@@ -9,3 +10,7 @@ mise run check
 ```
 
 See `CONTRIBUTING.md` for workflow and PR expectations.
+
+## License
+
+MIT. See `LICENSE`.

From 8736e0fa8dcdaae55f9558cbf2b8fc2bb602c419 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 19:12:47 +0530
Subject: [PATCH 10/13] docs: link related repositories

---
 README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README.md b/README.md
index 30da687..527d86f 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,15 @@
 
 Docs site and shared trail web viewer for Agent Trail.
 
+## Related Repositories
+
+Agent Trail is split across focused repositories:
+
+- [agent-trail/spec](https://github.com/agent-trail/spec) - format contract, JSON Schema, fixtures, and format ADRs.
+- [agent-trail/typescript-sdk](https://github.com/agent-trail/typescript-sdk) - TypeScript packages for Agent Trail files.
+- [agent-trail/cli](https://github.com/agent-trail/cli) - command-line tools for Agent Trail workflows.
+- [agent-trail/web](https://github.com/agent-trail/web) - docs site and shared trail web viewer.
+
 ## Development
 
 ```sh

From ac8aadb1377fc8770562b6b28b7c89899aef80c1 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:04:34 +0530
Subject: [PATCH 11/13] docs: adapt contributing for external contributors

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 66959b4..7fc3914 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ Thanks for helping improve Agent Trail.
 
 ## Before You Start
 
-- Open or pick up a Linear issue before starting larger changes.
+- For larger changes, open a GitHub issue or discussion first so maintainers can agree on scope.
 - Keep pull requests focused on one problem.
 - Avoid committing real local sessions, secrets, credentials, tokens, private logs, or unredacted user data.
 
@@ -35,7 +35,7 @@ When adding a package, tool, or GitHub Action, check the latest stable upstream
 Before opening a pull request:
 
 - Run `mise run check`.
-- Link the Linear issue.
+- Link the relevant GitHub issue or discussion, if one exists.
 - Summarize web UI, viewer, URL, or docs impact.
 - Include exact verification commands and results.
 

From f51b5a1914b31f3dd33dbecf7acfd4ceed874a98 Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:14:15 +0530
Subject: [PATCH 12/13] docs: remove non-spec rfc template

---
 .github/ISSUE_TEMPLATE/rfc.yml | 43 ----------------------------------
 1 file changed, 43 deletions(-)
 delete mode 100644 .github/ISSUE_TEMPLATE/rfc.yml

diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
deleted file mode 100644
index 9ea56e9..0000000
--- a/.github/ISSUE_TEMPLATE/rfc.yml
+++ /dev/null
@@ -1,43 +0,0 @@
-name: RFC / spec decision
-description: Propose a load-bearing Agent Trail format, schema, validation, package layout, or architecture decision.
-title: "rfc: "
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Use this before changing load-bearing shape such as normative format or schema semantics, validation terminology or behavior, versioning, hash semantics, artifact identity, package layout, durable architecture, or public URL shape.
-  - type: textarea
-    id: problem
-    attributes:
-      label: Problem or decision
-      description: What decision needs to be made, and why now?
-    validations:
-      required: true
-  - type: textarea
-    id: affected-surface
-    attributes:
-      label: Affected contract surface
-      description: Name the spec section, schema path, package API, CLI behavior, docs, ADRs, fixtures, or public URLs affected.
-    validations:
-      required: true
-  - type: textarea
-    id: proposal
-    attributes:
-      label: Proposal
-      description: State the exact rule or direction to adopt.
-    validations:
-      required: true
-  - type: textarea
-    id: alternatives
-    attributes:
-      label: Alternatives considered
-      description: List plausible options and tradeoffs.
-    validations:
-      required: true
-  - type: textarea
-    id: acceptance-criteria
-    attributes:
-      label: Acceptance criteria
-      description: Observable outcomes that prove the decision has been implemented.
-    validations:
-      required: true

From 1a67a68e138af1ff70bcd0403e27c6a40d35b29b Mon Sep 17 00:00:00 2001
From: Somasundaram Ayyappan <1802828+somus@users.noreply.github.com>
Date: Fri, 12 Jun 2026 21:27:06 +0530
Subject: [PATCH 13/13] ci: include workflow checks

---
 .github/PULL_REQUEST_TEMPLATE.md | 8 ++++++++
 mise.toml                        | 2 +-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 656a954..9ae7d85 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -4,6 +4,10 @@
 
 - 
 
+## Related Issue
+
+- 
+
 ## Public Impact
 
 - [ ] No public contract change
@@ -12,6 +16,10 @@
 - [ ] CLI behavior change
 - [ ] Public URL or docs behavior change
 
+Impact description:
+
+- 
+
 ## Verification
 
 - 
diff --git a/mise.toml b/mise.toml
index e8025ff..372aac9 100644
--- a/mise.toml
+++ b/mise.toml
@@ -14,7 +14,7 @@ run = "hk install"
 
 [tasks.check]
 description = "Run all repository checks"
-depends = ["lint", "test"]
+depends = ["lint", "test", "check:actions"]
 
 [tasks.lint]
 description = "Run project lint gates"