chore: add repository foundation

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,43 @@
+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

.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/cli/security/advisories/new
+    about: Report vulnerabilities privately instead of opening a public issue.

.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,43 @@
+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

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+# Pull Request
+
+## Summary
+
+- 
+
+## Related Issue
+
+- 
+
+## Public Impact
+
+- [ ] No public contract change
+- [ ] Spec or schema change
+- [ ] Public package API change
+- [ ] CLI behavior change
+- [ ] Public URL or docs behavior change
+
+Impact description:
+
+- 
+
+## Verification
+
+- 
+
+## Reviewer Notes
+
+- 

.github/workflows/guardrails.yml

@@ -0,0 +1,25 @@
+name: guardrails
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  guardrails:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9f698171ed81b15d1823a05fc7211befd50c8ae0 # v6.0.3
+        with:
+          persist-credentials: false
+      - uses: jdx/mise-action@dba19683ed58901619b14f395a24841710cb4925 # v4.1.0
+      - name: Run repository checks
+        run: mise run check

AGENTS.md

@@ -0,0 +1,27 @@
+# Agent Instructions
+
+This repo owns the Agent Trail CLI and source-agent adapter behavior compiled into the CLI.
+
+## Workflow
+
+- Start from the linked Linear issue or maintainer direction.
+- Keep changes scoped to CLI commands, adapter behavior, packaging, or CLI docs.
+- 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.
+
+## 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.
+
+## 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`.
+- Link the Linear issue.
+- State CLI behavior, adapter behavior, or packaging impact.
+- Include exact verification commands and results.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Thanks for helping improve Agent Trail.
+
+## Before You Start
+
+- 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.
+
+## Local Setup
+
+Install tools and hooks:
+
+```sh
+mise run setup
+```
+
+Common tasks:
+
+```sh
+mise run check
+mise run lint
+mise run test
+```
+
+`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
+
+Before opening a pull request:
+
+- Run `mise run check`.
+- Link the relevant GitHub issue or discussion, if one exists.
+- Summarize CLI behavior, adapter behavior, or packaging impact.
+- Include exact verification commands and results.
+
+Pull requests are squash-merged. Keep branches narrow and delete them after merge.

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.

README.md

@@ -1,2 +1,25 @@
-# cli
-Agent Trail command-line interface.
+# Agent Trail CLI
+
+Command-line tools for discovering, validating, loading, sharing, and exporting Agent Trail files.
+
+## 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
+mise run setup
+mise run check
+```
+
+See `CONTRIBUTING.md` for workflow and PR expectations.
+
+## License
+
+MIT. See `LICENSE`.

SECURITY.md

@@ -0,0 +1,9 @@
+# Security
+
+Do not open public issues for vulnerabilities.
+
+Use GitHub private vulnerability reporting:
+
+https://github.com/agent-trail/cli/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.

hk.pkl

@@ -0,0 +1,22 @@
+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
+  ["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
+  }
+}

mise.toml

@@ -0,0 +1,29 @@
+[tools]
+bun = "1.3.14"
+"aqua:jdx/hk" = "1.48.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", "check:actions"]
+
+[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 = "if [ -d .github/workflows ]; then actionlint && zizmor .github/workflows; else echo 'No GitHub Actions workflows configured.'; fi"

renovate.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended"],
+  "labels": ["dependencies"]
+}