detached 574518c

Add development and contribution guidelines [release=skip]

commit
574518c08eb3986ecf84a8d07148ec4b869ba930
author
patriceckhart · · 2026-07-15 17:20 UTC
committer
patriceckhart · · 2026-07-16 09:23 UTC
parent
24f1547
signature
unsigned
2 files · +368 -0
Unified
UnifiedSplit
A AGENTS.md +191 -0
@@ -0,0 +1,191 @@
1+# Working Agreement for zot
2+
3+This file defines how automated coding assistants should work in this repository. Treat it as a practical operating manual, not a substitute for reading the code.
4+
5+## Product intent
6+
7+zot is a compact Go coding-agent harness. Changes should preserve its defining properties:
8+
9+- one portable binary
10+- a provider-neutral agent engine
11+- a terminal UI without a framework dependency
12+- extensions that communicate through subprocess JSON-RPC
13+- predictable behavior on macOS, Linux, and Windows
14+- a small dependency and operational footprint
15+
16+Prefer a narrow, explicit implementation over a generalized subsystem. New abstractions must earn their cost through a real boundary or repeated use.
17+
18+## Starting a task
19+
20+Build context before editing:
21+
22+1. Inspect `git status --short`. Existing modifications may belong to the user or another agent.
23+2. Locate and read every `AGENTS.md` that governs the target path.
24+3. Read the owning implementation, nearby tests, and any user-facing documentation for the behavior.
25+4. Reproduce reported failures when feasible. Record expected behavior separately from observed behavior.
26+5. For GitHub work, inspect the issue or pull request with `gh` if it is available. Do not change branches merely to review a pull request.
27+
28+Do not use a search result or one function as a complete model of a feature. Follow calls across package boundaries and inspect persisted or streamed representations when relevant.
29+
30+## Code ownership map
31+
32+Put behavior in the package that owns the concern:
33+
34+| Area | Responsibility |
35+|---|---|
36+| `packages/core` | Agent loop, messages, tool contracts, events, confirmation, sessions, compaction |
37+| `packages/provider` | Provider clients, wire formats, streaming, retries, model metadata and discovery |
38+| `packages/provider/auth` | Login flows, credential lookup, refresh, and storage |
39+| `packages/agent` | CLI configuration, model selection, runtime assembly, RPC, and Zotfiles |
40+| `packages/agent/modes` | Interactive, print, JSON, dialog, bot, and Telegram interfaces |
41+| `packages/agent/extensions` | Extension process lifecycle and host integration |
42+| `packages/agent/extproto` | Extension wire protocol |
43+| `packages/agent/ext` | Public extension SDK |
44+| `packages/agent/skills` | Skill discovery and loading |
45+| `packages/agent/swarm` | Background-agent state, supervision, and persistence |
46+| `packages/agent/tools` | Built-in tools, permission checks, and jail behavior |
47+| `packages/tui` | Terminal input, layout, rendering, markdown, themes, and images |
48+| `packages/ignore` | Ignore-pattern matching |
49+
50+Provider quirks must not leak into `packages/core`. Terminal escape handling and visual layout belong in `packages/tui`. Avoid making the interactive mode a catch-all when a focused package can own the behavior.
51+
52+## Correctness contracts
53+
54+Some parts of zot require extra care because small mistakes corrupt state or weaken user protections.
55+
56+### Agent events and sessions
57+
58+- Keep streamed events and stored transcripts structurally valid.
59+- Preserve tool-call and tool-result pairing, including cancellation and error paths.
60+- Maintain compatibility with existing session files unless a migration is explicitly part of the task.
61+- Validate replay, resume, fork, import, and export paths when changing shared session structures.
62+
63+### Providers
64+
65+- Keep request construction, response parsing, streaming state, and retry classification inside `packages/provider`.
66+- Never assume two OpenAI-compatible services have identical edge behavior.
67+- When changing model metadata, verify provider ID, model ID, context size, output limit, reasoning support, routing, and pricing independently.
68+- Tests must use local servers or fixtures. Do not make paid or credentialed API calls.
69+
70+### Credentials and private data
71+
72+- Treat API keys, OAuth tokens, session text, extension payloads, and local state as sensitive.
73+- Never include secrets in logs, fixtures, snapshots, errors, or commits.
74+- Credential files must retain restrictive permissions where the platform supports them.
75+- Test authentication with synthetic values and isolated temporary directories.
76+
77+### Tools and confinement
78+
79+- Permission checks must fail closed.
80+- Resolve path and symlink behavior before allowing filesystem access.
81+- Jail mode is an accident-prevention guardrail, not a security sandbox. Documentation and errors must not claim stronger isolation.
82+- Preserve confirmation semantics across every mode. A convenient fallback must not silently grant access.
83+
84+### Extensions and RPC
85+
86+- Existing JSON-RPC and extension clients are compatibility surfaces.
87+- Add fields in a backward-compatible way and tolerate peers that do not send newly introduced fields.
88+- Keep stdout machine-readable where it carries protocol data. Diagnostics belong on stderr or in the established event channel.
89+- Ensure child processes are cleaned up on normal exit, cancellation, and startup failure.
90+
91+### Terminal behavior
92+
93+- Rendering code must account for ANSI sequences, Unicode display width, wrapping, narrow terminals, and partial streamed content.
94+- Avoid tests that depend on a developer's terminal capabilities.
95+- Changes involving input, resize, clipboard, process control, paths, shells, or signals require inspection of build-tagged counterparts.
96+
97+## Implementation approach
98+
99+For fixes, locate the earliest broken invariant and test there. A UI symptom may originate in provider parsing, event construction, or session replay. Repair the owning layer rather than masking the symptom downstream.
100+
101+For features, identify all public surfaces before coding: flags, configuration, slash commands, SDK, RPC, extensions, persisted state, provider behavior, and docs. Implement only the surfaces required for a complete first version.
102+
103+While editing:
104+
105+- Preserve unrelated working-tree changes.
106+- Use idiomatic Go and standard-library facilities when they are sufficient.
107+- Keep functions and interfaces focused. Do not introduce an interface solely to mock one call unless it improves the production boundary.
108+- Return errors with enough context to identify the failed operation, without exposing private data.
109+- Thread `context.Context` through blocking work and honor cancellation.
110+- Avoid time-based synchronization in tests. Prefer channels, explicit hooks, or polling with a deadline.
111+- Use `t.TempDir()` and `t.Setenv()` for isolated tests. Restore package globals in cleanup.
112+- Do not perform opportunistic refactors outside the requested change.
113+
114+If intentional behavior appears removable or requirements conflict materially, ask the user before proceeding.
115+
116+## Validation ladder
117+
118+Match validation effort to the change, then finish with repository-wide checks when code changed.
119+
120+1. Add or update a regression test in the owning package.
121+2. During iteration, run the smallest relevant test, for example:
122+
123+ ```sh
124+ go test ./packages/provider -run TestName
125+ ```
126+
127+3. Format every changed Go file with `gofmt`.
128+4. Run the complete suite:
129+
130+ ```sh
131+ go test ./...
132+ ```
133+
134+ `make test` additionally enables the race detector and is preferred for concurrency-sensitive work.
135+
136+5. Run `go vet ./...` for changes involving concurrency, interfaces, formatting calls, unsafe behavior, process lifecycle, or broad runtime wiring.
137+6. Before reporting completion, inspect:
138+
139+ ```sh
140+ git diff --check
141+ git status --short
142+ git diff
143+ ```
144+
145+Do not hide failures, weaken assertions, or claim validation that was not run. If a check cannot run, state the command and the reason.
146+
147+Documentation-only changes do not require the Go test suite unless they alter generated or executable examples. They still require diff and status review.
148+
149+## Documentation duties
150+
151+Update documentation in the same change whenever users, integrators, or extension authors would observe different behavior. Relevant locations include `README.md`, `docs/rpc.md`, `docs/extensions.md`, `docs/skills.md`, `docs/themes.md`, and `docs/zotfiles.md`.
152+
153+Examples must match real flags and schemas. State limitations plainly, especially around sandboxing, provider support, compatibility, and platform differences.
154+
155+## Dependency policy
156+
157+zot's single-binary design and small footprint are product requirements.
158+
159+- Prefer the standard library or existing dependencies.
160+- Explain why a new dependency is necessary before adding it.
161+- Review transitive dependencies and platform implications.
162+- Do not add a TUI framework for behavior the current renderer can support.
163+- Keep `go.mod` and `go.sum` changes limited to the requested work.
164+
165+## Source-control safety
166+
167+The working directory may contain changes from other people or agents.
168+
169+Allowed inspection commands include `git status`, `git diff`, `git log`, `git show`, and `git blame`. Avoid destructive or broad commands such as `git reset --hard`, `git clean`, `git checkout .`, and blanket staging.
170+
171+Do not commit, create or switch branches, rebase, push, tag, or open a pull request unless the user explicitly requests that operation. Permission to edit files is not permission to commit them.
172+
173+When a commit is requested:
174+
175+- include only files changed for the current task
176+- stage paths explicitly
177+- review the staged diff before committing
178+- use a concise imperative subject that describes the behavior
179+- never bypass hooks without explicit approval
180+
181+When a pull request is requested, run the full validation suite first, summarize compatibility and user-visible effects, and mention any failed or skipped checks.
182+
183+## Completion report
184+
185+A final response should be brief and factual. Include:
186+
187+- what changed and where
188+- which checks were run and their results
189+- any unresolved risk, skipped validation, or follow-up needed
190+
191+Do not report success while tests are failing. Do not include unrelated cleanup suggestions unless they materially affect the requested work.
@@ -0,0 +1,191 @@
1+# Working Agreement for zot
2+
3+This file defines how automated coding assistants should work in this repository. Treat it as a practical operating manual, not a substitute for reading the code.
4+
5+## Product intent
6+
7+zot is a compact Go coding-agent harness. Changes should preserve its defining properties:
8+
9+- one portable binary
10+- a provider-neutral agent engine
11+- a terminal UI without a framework dependency
12+- extensions that communicate through subprocess JSON-RPC
13+- predictable behavior on macOS, Linux, and Windows
14+- a small dependency and operational footprint
15+
16+Prefer a narrow, explicit implementation over a generalized subsystem. New abstractions must earn their cost through a real boundary or repeated use.
17+
18+## Starting a task
19+
20+Build context before editing:
21+
22+1. Inspect `git status --short`. Existing modifications may belong to the user or another agent.
23+2. Locate and read every `AGENTS.md` that governs the target path.
24+3. Read the owning implementation, nearby tests, and any user-facing documentation for the behavior.
25+4. Reproduce reported failures when feasible. Record expected behavior separately from observed behavior.
26+5. For GitHub work, inspect the issue or pull request with `gh` if it is available. Do not change branches merely to review a pull request.
27+
28+Do not use a search result or one function as a complete model of a feature. Follow calls across package boundaries and inspect persisted or streamed representations when relevant.
29+
30+## Code ownership map
31+
32+Put behavior in the package that owns the concern:
33+
34+| Area | Responsibility |
35+|---|---|
36+| `packages/core` | Agent loop, messages, tool contracts, events, confirmation, sessions, compaction |
37+| `packages/provider` | Provider clients, wire formats, streaming, retries, model metadata and discovery |
38+| `packages/provider/auth` | Login flows, credential lookup, refresh, and storage |
39+| `packages/agent` | CLI configuration, model selection, runtime assembly, RPC, and Zotfiles |
40+| `packages/agent/modes` | Interactive, print, JSON, dialog, bot, and Telegram interfaces |
41+| `packages/agent/extensions` | Extension process lifecycle and host integration |
42+| `packages/agent/extproto` | Extension wire protocol |
43+| `packages/agent/ext` | Public extension SDK |
44+| `packages/agent/skills` | Skill discovery and loading |
45+| `packages/agent/swarm` | Background-agent state, supervision, and persistence |
46+| `packages/agent/tools` | Built-in tools, permission checks, and jail behavior |
47+| `packages/tui` | Terminal input, layout, rendering, markdown, themes, and images |
48+| `packages/ignore` | Ignore-pattern matching |
49+
50+Provider quirks must not leak into `packages/core`. Terminal escape handling and visual layout belong in `packages/tui`. Avoid making the interactive mode a catch-all when a focused package can own the behavior.
51+
52+## Correctness contracts
53+
54+Some parts of zot require extra care because small mistakes corrupt state or weaken user protections.
55+
56+### Agent events and sessions
57+
58+- Keep streamed events and stored transcripts structurally valid.
59+- Preserve tool-call and tool-result pairing, including cancellation and error paths.
60+- Maintain compatibility with existing session files unless a migration is explicitly part of the task.
61+- Validate replay, resume, fork, import, and export paths when changing shared session structures.
62+
63+### Providers
64+
65+- Keep request construction, response parsing, streaming state, and retry classification inside `packages/provider`.
66+- Never assume two OpenAI-compatible services have identical edge behavior.
67+- When changing model metadata, verify provider ID, model ID, context size, output limit, reasoning support, routing, and pricing independently.
68+- Tests must use local servers or fixtures. Do not make paid or credentialed API calls.
69+
70+### Credentials and private data
71+
72+- Treat API keys, OAuth tokens, session text, extension payloads, and local state as sensitive.
73+- Never include secrets in logs, fixtures, snapshots, errors, or commits.
74+- Credential files must retain restrictive permissions where the platform supports them.
75+- Test authentication with synthetic values and isolated temporary directories.
76+
77+### Tools and confinement
78+
79+- Permission checks must fail closed.
80+- Resolve path and symlink behavior before allowing filesystem access.
81+- Jail mode is an accident-prevention guardrail, not a security sandbox. Documentation and errors must not claim stronger isolation.
82+- Preserve confirmation semantics across every mode. A convenient fallback must not silently grant access.
83+
84+### Extensions and RPC
85+
86+- Existing JSON-RPC and extension clients are compatibility surfaces.
87+- Add fields in a backward-compatible way and tolerate peers that do not send newly introduced fields.
88+- Keep stdout machine-readable where it carries protocol data. Diagnostics belong on stderr or in the established event channel.
89+- Ensure child processes are cleaned up on normal exit, cancellation, and startup failure.
90+
91+### Terminal behavior
92+
93+- Rendering code must account for ANSI sequences, Unicode display width, wrapping, narrow terminals, and partial streamed content.
94+- Avoid tests that depend on a developer's terminal capabilities.
95+- Changes involving input, resize, clipboard, process control, paths, shells, or signals require inspection of build-tagged counterparts.
96+
97+## Implementation approach
98+
99+For fixes, locate the earliest broken invariant and test there. A UI symptom may originate in provider parsing, event construction, or session replay. Repair the owning layer rather than masking the symptom downstream.
100+
101+For features, identify all public surfaces before coding: flags, configuration, slash commands, SDK, RPC, extensions, persisted state, provider behavior, and docs. Implement only the surfaces required for a complete first version.
102+
103+While editing:
104+
105+- Preserve unrelated working-tree changes.
106+- Use idiomatic Go and standard-library facilities when they are sufficient.
107+- Keep functions and interfaces focused. Do not introduce an interface solely to mock one call unless it improves the production boundary.
108+- Return errors with enough context to identify the failed operation, without exposing private data.
109+- Thread `context.Context` through blocking work and honor cancellation.
110+- Avoid time-based synchronization in tests. Prefer channels, explicit hooks, or polling with a deadline.
111+- Use `t.TempDir()` and `t.Setenv()` for isolated tests. Restore package globals in cleanup.
112+- Do not perform opportunistic refactors outside the requested change.
113+
114+If intentional behavior appears removable or requirements conflict materially, ask the user before proceeding.
115+
116+## Validation ladder
117+
118+Match validation effort to the change, then finish with repository-wide checks when code changed.
119+
120+1. Add or update a regression test in the owning package.
121+2. During iteration, run the smallest relevant test, for example:
122+
123+ ```sh
124+ go test ./packages/provider -run TestName
125+ ```
126+
127+3. Format every changed Go file with `gofmt`.
128+4. Run the complete suite:
129+
130+ ```sh
131+ go test ./...
132+ ```
133+
134+ `make test` additionally enables the race detector and is preferred for concurrency-sensitive work.
135+
136+5. Run `go vet ./...` for changes involving concurrency, interfaces, formatting calls, unsafe behavior, process lifecycle, or broad runtime wiring.
137+6. Before reporting completion, inspect:
138+
139+ ```sh
140+ git diff --check
141+ git status --short
142+ git diff
143+ ```
144+
145+Do not hide failures, weaken assertions, or claim validation that was not run. If a check cannot run, state the command and the reason.
146+
147+Documentation-only changes do not require the Go test suite unless they alter generated or executable examples. They still require diff and status review.
148+
149+## Documentation duties
150+
151+Update documentation in the same change whenever users, integrators, or extension authors would observe different behavior. Relevant locations include `README.md`, `docs/rpc.md`, `docs/extensions.md`, `docs/skills.md`, `docs/themes.md`, and `docs/zotfiles.md`.
152+
153+Examples must match real flags and schemas. State limitations plainly, especially around sandboxing, provider support, compatibility, and platform differences.
154+
155+## Dependency policy
156+
157+zot's single-binary design and small footprint are product requirements.
158+
159+- Prefer the standard library or existing dependencies.
160+- Explain why a new dependency is necessary before adding it.
161+- Review transitive dependencies and platform implications.
162+- Do not add a TUI framework for behavior the current renderer can support.
163+- Keep `go.mod` and `go.sum` changes limited to the requested work.
164+
165+## Source-control safety
166+
167+The working directory may contain changes from other people or agents.
168+
169+Allowed inspection commands include `git status`, `git diff`, `git log`, `git show`, and `git blame`. Avoid destructive or broad commands such as `git reset --hard`, `git clean`, `git checkout .`, and blanket staging.
170+
171+Do not commit, create or switch branches, rebase, push, tag, or open a pull request unless the user explicitly requests that operation. Permission to edit files is not permission to commit them.
172+
173+When a commit is requested:
174+
175+- include only files changed for the current task
176+- stage paths explicitly
177+- review the staged diff before committing
178+- use a concise imperative subject that describes the behavior
179+- never bypass hooks without explicit approval
180+
181+When a pull request is requested, run the full validation suite first, summarize compatibility and user-visible effects, and mention any failed or skipped checks.
182+
183+## Completion report
184+
185+A final response should be brief and factual. Include:
186+
187+- what changed and where
188+- which checks were run and their results
189+- any unresolved risk, skipped validation, or follow-up needed
190+
191+Do not report success while tests are failing. Do not include unrelated cleanup suggestions unless they materially affect the requested work.
A CONTRIBUTING.md +177 -0
@@ -0,0 +1,177 @@
1+# Contributing to zot
2+
3+Contributions are welcome, including bug reports, design feedback, documentation, tests, and code. This guide explains what makes a contribution easy to evaluate and safe to merge.
4+
5+## Choose the right starting point
6+
7+### Reporting a defect
8+
9+Use the bug-report template and provide enough information for someone else to reproduce the problem:
10+
11+- the output of `zot --version`
12+- operating system and terminal
13+- provider and model, when relevant
14+- the smallest sequence of actions that triggers the problem
15+- expected and actual results
16+- relevant logs with credentials and private session content removed
17+
18+Search existing issues first. If the behavior only occurs with a particular provider, include the HTTP status and sanitized response details when available, but never post an API key, OAuth token, authorization header, or full private transcript.
19+
20+### Suggesting a capability
21+
22+Start with the feature-request template. Describe the workflow that is difficult today before proposing an interface. Useful proposals explain:
23+
24+- who encounters the problem
25+- why existing flags, extensions, or configuration do not solve it
26+- how the new behavior would appear in the CLI, TUI, SDK, or protocol
27+- compatibility or migration concerns
28+- reasonable alternatives
29+
30+For changes that introduce a public API, alter stored data, modify an extension protocol, or span several packages, wait for design feedback before investing in an implementation.
31+
32+### Small corrections
33+
34+Focused typo, documentation, and test improvements can usually go directly to a pull request. Keep them separate from behavioral changes.
35+
36+## Design boundaries
37+
38+zot is intended to remain a lightweight, single-binary application. A contribution should fit that direction rather than increasing scope by default.
39+
40+The major ownership boundaries are:
41+
42+- `packages/core`: provider-independent agent behavior and session structures
43+- `packages/provider`: provider requests, streaming responses, model discovery, retries, and wire-specific behavior
44+- `packages/provider/auth`: credential and login handling
45+- `packages/agent`: command-line orchestration, configuration, runtime assembly, RPC, and Zotfiles
46+- `packages/agent/modes`: interactive and non-interactive user modes
47+- `packages/agent/extensions`, `extproto`, and `ext`: extension hosting, protocol, and SDK
48+- `packages/agent/skills`: reusable instruction discovery
49+- `packages/agent/swarm`: background-agent supervision and state
50+- `packages/agent/tools`: built-in tools, permissions, and jail checks
51+- `packages/tui`: terminal mechanics and rendering
52+- `packages/ignore`: ignore matching
53+
54+Keep provider-specific decisions out of the core agent loop. Keep terminal rendering out of orchestration code. If a feature can be delivered cleanly as an extension, consider that before expanding the built-in surface.
55+
56+New dependencies need a clear benefit. The standard library and current dependency set are preferred, particularly for functionality that would otherwise increase binary size or complicate cross-platform builds.
57+
58+## Preparing a development checkout
59+
60+Use the Go version declared in `go.mod`, then build from the repository root:
61+
62+```sh
63+go mod download
64+make build
65+./bin/zot --version
66+```
67+
68+Useful commands:
69+
70+```sh
71+make build # compile ./bin/zot
72+make run # build and start the interactive application
73+make test # run all tests with the race detector
74+make lint # run go vet and verify gofmt
75+```
76+
77+Tests must not depend on real provider credentials, paid model calls, a developer's global zot state, or a specific terminal. Use local HTTP test servers, fixtures, temporary directories, and synthetic credentials.
78+
79+## Making a change
80+
81+A reviewable change has one purpose. Avoid bundling renames, formatting churn, generated metadata updates, or unrelated refactors into the same pull request.
82+
83+For a bug fix:
84+
85+1. Demonstrate the failure with a focused test when practical.
86+2. Find the package where the invalid state first appears.
87+3. Fix that layer rather than compensating in the UI or another downstream consumer.
88+4. Exercise neighboring cases that use the same parser, event path, or persisted format.
89+
90+For new behavior:
91+
92+1. Identify every user-visible and integration surface involved.
93+2. Preserve existing configuration, sessions, RPC clients, and extensions unless a breaking change has been agreed upon.
94+3. Add tests in the package that owns the behavior.
95+4. Update the relevant documentation in the same pull request.
96+
97+Follow ordinary Go conventions. Format changed Go files with `gofmt`, propagate cancellation through `context.Context`, and wrap errors with useful operational context. Error messages and logs must not expose credentials or private content.
98+
99+The repository's `AGENTS.md` contains additional implementation guidance for automated tools and is also useful as an architecture reference for human contributors.
100+
101+## Areas requiring additional checks
102+
103+### Providers and models
104+
105+Provider contributions should cover request serialization, successful parsing, streamed events, API errors, and cancellation using local fixtures or an `httptest` server. Confirm model identifiers, context and output limits, reasoning support, provider routing, and pricing data from authoritative sources.
106+
107+Do not treat all OpenAI-compatible endpoints as interchangeable. Service-specific behavior belongs in `packages/provider` and should be represented by tests.
108+
109+### Sessions and event streams
110+
111+Changes to messages or events must preserve valid tool-call and tool-result sequences. Check persistence and replay, not only live output. Consider resume, compaction, import, export, and forks whenever a shared session representation changes.
112+
113+### RPC and extensions
114+
115+The RPC and extension schemas are consumed outside this repository. Prefer additive changes, define behavior when a peer omits a new field, and keep protocol stdout free of human diagnostics. Update `docs/rpc.md` or `docs/extensions.md` for contract changes.
116+
117+### Permissions and jail behavior
118+
119+Permission failures must deny the operation. Test path traversal, symlink resolution, and cancellation where applicable. Jail mode is a safety guardrail rather than a hard isolation boundary, and contributions must preserve that distinction.
120+
121+### Operating systems and terminals
122+
123+CI runs on Linux, macOS, and Windows. Process handling, signals, shell invocation, filesystem paths, clipboard access, resize behavior, and terminal input often have platform-specific implementations. Inspect all build-tagged variants and avoid assumptions about Unix paths or ANSI support.
124+
125+## Verification
126+
127+Run focused package tests while developing. Before opening a pull request that changes Go code, run:
128+
129+```sh
130+gofmt -w <changed-go-files>
131+go vet ./...
132+go test -race ./...
133+git diff --check
134+```
135+
136+`make lint` and `make test` provide the repository equivalents for the lint and test steps.
137+
138+Documentation-only pull requests do not need the Go suite unless they modify executable examples or generated content. They should still be checked for accurate commands, links, and formatting.
139+
140+If a validation command cannot pass because of an unrelated repository or environment problem, describe the exact command and failure in the pull request. Do not silently omit it.
141+
142+## Pull request shape
143+
144+Open the pull request against `main` and include:
145+
146+- the problem being addressed
147+- the chosen solution and why it belongs in zot
148+- tests added or updated
149+- commands used for verification
150+- user-visible, compatibility, and platform effects
151+- a linked issue when one exists
152+
153+Keep commits understandable and use concise, imperative subjects. Update your branch normally when review requests changes. Do not force-push over review history unless there is a specific reason and reviewers have been informed.
154+
155+A reviewer may ask for a contribution to be reduced in scope, moved to a different package, implemented as an extension, or split into independent pull requests. This is intended to keep behavior maintainable and does not diminish the underlying use case.
156+
157+## Documentation locations
158+
159+Choose the document that owns the public surface:
160+
161+- `README.md` for installation, authentication, flags, common commands, modes, and user workflows
162+- `docs/providers.md` for provider-specific setup and behavior
163+- `docs/rpc.md` for the embedding protocol
164+- `docs/extensions.md` for extension authors
165+- `docs/skills.md` for reusable skills
166+- `docs/themes.md` for theme files
167+- `docs/zotfiles.md` for portable agents
168+
169+Examples should be runnable and limitations should be stated directly.
170+
171+## Sensitive security reports
172+
173+Do not open a public issue containing an exploitable vulnerability, live credential, or private user data. Use GitHub's private vulnerability reporting for this repository when available. Include a minimal reproduction, affected versions, impact, and any suggested mitigation without using production secrets.
174+
175+## License
176+
177+By submitting a contribution, you agree that it may be distributed under the repository's [MIT License](LICENSE).
@@ -0,0 +1,177 @@
1+# Contributing to zot
2+
3+Contributions are welcome, including bug reports, design feedback, documentation, tests, and code. This guide explains what makes a contribution easy to evaluate and safe to merge.
4+
5+## Choose the right starting point
6+
7+### Reporting a defect
8+
9+Use the bug-report template and provide enough information for someone else to reproduce the problem:
10+
11+- the output of `zot --version`
12+- operating system and terminal
13+- provider and model, when relevant
14+- the smallest sequence of actions that triggers the problem
15+- expected and actual results
16+- relevant logs with credentials and private session content removed
17+
18+Search existing issues first. If the behavior only occurs with a particular provider, include the HTTP status and sanitized response details when available, but never post an API key, OAuth token, authorization header, or full private transcript.
19+
20+### Suggesting a capability
21+
22+Start with the feature-request template. Describe the workflow that is difficult today before proposing an interface. Useful proposals explain:
23+
24+- who encounters the problem
25+- why existing flags, extensions, or configuration do not solve it
26+- how the new behavior would appear in the CLI, TUI, SDK, or protocol
27+- compatibility or migration concerns
28+- reasonable alternatives
29+
30+For changes that introduce a public API, alter stored data, modify an extension protocol, or span several packages, wait for design feedback before investing in an implementation.
31+
32+### Small corrections
33+
34+Focused typo, documentation, and test improvements can usually go directly to a pull request. Keep them separate from behavioral changes.
35+
36+## Design boundaries
37+
38+zot is intended to remain a lightweight, single-binary application. A contribution should fit that direction rather than increasing scope by default.
39+
40+The major ownership boundaries are:
41+
42+- `packages/core`: provider-independent agent behavior and session structures
43+- `packages/provider`: provider requests, streaming responses, model discovery, retries, and wire-specific behavior
44+- `packages/provider/auth`: credential and login handling
45+- `packages/agent`: command-line orchestration, configuration, runtime assembly, RPC, and Zotfiles
46+- `packages/agent/modes`: interactive and non-interactive user modes
47+- `packages/agent/extensions`, `extproto`, and `ext`: extension hosting, protocol, and SDK
48+- `packages/agent/skills`: reusable instruction discovery
49+- `packages/agent/swarm`: background-agent supervision and state
50+- `packages/agent/tools`: built-in tools, permissions, and jail checks
51+- `packages/tui`: terminal mechanics and rendering
52+- `packages/ignore`: ignore matching
53+
54+Keep provider-specific decisions out of the core agent loop. Keep terminal rendering out of orchestration code. If a feature can be delivered cleanly as an extension, consider that before expanding the built-in surface.
55+
56+New dependencies need a clear benefit. The standard library and current dependency set are preferred, particularly for functionality that would otherwise increase binary size or complicate cross-platform builds.
57+
58+## Preparing a development checkout
59+
60+Use the Go version declared in `go.mod`, then build from the repository root:
61+
62+```sh
63+go mod download
64+make build
65+./bin/zot --version
66+```
67+
68+Useful commands:
69+
70+```sh
71+make build # compile ./bin/zot
72+make run # build and start the interactive application
73+make test # run all tests with the race detector
74+make lint # run go vet and verify gofmt
75+```
76+
77+Tests must not depend on real provider credentials, paid model calls, a developer's global zot state, or a specific terminal. Use local HTTP test servers, fixtures, temporary directories, and synthetic credentials.
78+
79+## Making a change
80+
81+A reviewable change has one purpose. Avoid bundling renames, formatting churn, generated metadata updates, or unrelated refactors into the same pull request.
82+
83+For a bug fix:
84+
85+1. Demonstrate the failure with a focused test when practical.
86+2. Find the package where the invalid state first appears.
87+3. Fix that layer rather than compensating in the UI or another downstream consumer.
88+4. Exercise neighboring cases that use the same parser, event path, or persisted format.
89+
90+For new behavior:
91+
92+1. Identify every user-visible and integration surface involved.
93+2. Preserve existing configuration, sessions, RPC clients, and extensions unless a breaking change has been agreed upon.
94+3. Add tests in the package that owns the behavior.
95+4. Update the relevant documentation in the same pull request.
96+
97+Follow ordinary Go conventions. Format changed Go files with `gofmt`, propagate cancellation through `context.Context`, and wrap errors with useful operational context. Error messages and logs must not expose credentials or private content.
98+
99+The repository's `AGENTS.md` contains additional implementation guidance for automated tools and is also useful as an architecture reference for human contributors.
100+
101+## Areas requiring additional checks
102+
103+### Providers and models
104+
105+Provider contributions should cover request serialization, successful parsing, streamed events, API errors, and cancellation using local fixtures or an `httptest` server. Confirm model identifiers, context and output limits, reasoning support, provider routing, and pricing data from authoritative sources.
106+
107+Do not treat all OpenAI-compatible endpoints as interchangeable. Service-specific behavior belongs in `packages/provider` and should be represented by tests.
108+
109+### Sessions and event streams
110+
111+Changes to messages or events must preserve valid tool-call and tool-result sequences. Check persistence and replay, not only live output. Consider resume, compaction, import, export, and forks whenever a shared session representation changes.
112+
113+### RPC and extensions
114+
115+The RPC and extension schemas are consumed outside this repository. Prefer additive changes, define behavior when a peer omits a new field, and keep protocol stdout free of human diagnostics. Update `docs/rpc.md` or `docs/extensions.md` for contract changes.
116+
117+### Permissions and jail behavior
118+
119+Permission failures must deny the operation. Test path traversal, symlink resolution, and cancellation where applicable. Jail mode is a safety guardrail rather than a hard isolation boundary, and contributions must preserve that distinction.
120+
121+### Operating systems and terminals
122+
123+CI runs on Linux, macOS, and Windows. Process handling, signals, shell invocation, filesystem paths, clipboard access, resize behavior, and terminal input often have platform-specific implementations. Inspect all build-tagged variants and avoid assumptions about Unix paths or ANSI support.
124+
125+## Verification
126+
127+Run focused package tests while developing. Before opening a pull request that changes Go code, run:
128+
129+```sh
130+gofmt -w <changed-go-files>
131+go vet ./...
132+go test -race ./...
133+git diff --check
134+```
135+
136+`make lint` and `make test` provide the repository equivalents for the lint and test steps.
137+
138+Documentation-only pull requests do not need the Go suite unless they modify executable examples or generated content. They should still be checked for accurate commands, links, and formatting.
139+
140+If a validation command cannot pass because of an unrelated repository or environment problem, describe the exact command and failure in the pull request. Do not silently omit it.
141+
142+## Pull request shape
143+
144+Open the pull request against `main` and include:
145+
146+- the problem being addressed
147+- the chosen solution and why it belongs in zot
148+- tests added or updated
149+- commands used for verification
150+- user-visible, compatibility, and platform effects
151+- a linked issue when one exists
152+
153+Keep commits understandable and use concise, imperative subjects. Update your branch normally when review requests changes. Do not force-push over review history unless there is a specific reason and reviewers have been informed.
154+
155+A reviewer may ask for a contribution to be reduced in scope, moved to a different package, implemented as an extension, or split into independent pull requests. This is intended to keep behavior maintainable and does not diminish the underlying use case.
156+
157+## Documentation locations
158+
159+Choose the document that owns the public surface:
160+
161+- `README.md` for installation, authentication, flags, common commands, modes, and user workflows
162+- `docs/providers.md` for provider-specific setup and behavior
163+- `docs/rpc.md` for the embedding protocol
164+- `docs/extensions.md` for extension authors
165+- `docs/skills.md` for reusable skills
166+- `docs/themes.md` for theme files
167+- `docs/zotfiles.md` for portable agents
168+
169+Examples should be runnable and limitations should be stated directly.
170+
171+## Sensitive security reports
172+
173+Do not open a public issue containing an exploitable vulnerability, live credential, or private user data. Use GitHub's private vulnerability reporting for this repository when available. Include a minimal reproduction, affected versions, impact, and any suggested mitigation without using production secrets.
174+
175+## License
176+
177+By submitting a contribution, you agree that it may be distributed under the repository's [MIT License](LICENSE).

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. Elsewhere: into the side panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 476

↑↓ moveenter openesc close