Polish AgentTrace publication community docs

CODE_OF_CONDUCT.md

@@ -1,9 +1,25 @@
 # Code of Conduct
 
-AgentTrace is an engineering project and its community should be useful, professional, and safe to participate in.
+AgentTrace is an open-source engineering project. We want discussion, review, and collaboration to stay useful, respectful, and safe for everyone participating.
 
-Contributors are expected to discuss ideas and code on their merits, give actionable technical feedback, respect differing experience levels, and avoid harassment, threats, discriminatory language, doxxing, sexualized conduct, or deliberate disruption.
+## Expected behavior
 
-Project maintainers may edit or remove abusive content, close or lock discussions, reject contributions, or restrict participation when conduct materially harms the project or its contributors. Enforcement decisions should be proportionate, documented internally where appropriate, and focused on protecting productive participation rather than winning arguments.
+- Discuss code, telemetry evidence, and ideas on their merits.
+- Give specific, actionable feedback and assume good faith where reasonable.
+- Respect different experience levels, backgrounds, and communication styles.
+- Keep technical disagreement focused on the work, not the person.
+- Protect private information, credentials, and sensitive trace data.
 
-If you need to report conduct that should not be handled in public, use a private repository contact mechanism where available. Do not post personal or sensitive information in an issue.
+## Unacceptable behavior
+
+Harassment, threats, discriminatory or sexualized language, doxxing, personal attacks, intimidation, deliberate disruption, or publishing another person's private information without permission are not acceptable.
+
+## Scope
+
+This policy applies to issues, pull requests, reviews, discussions, project-managed community spaces, and direct project interactions connected to AgentTrace.
+
+## Enforcement
+
+Maintainers may edit or remove abusive content, close or lock threads, reject contributions, or restrict participation when behavior materially harms contributors or the project. Responses should be proportionate and focused on restoring productive participation.
+
+For concerns that should not be handled publicly, use a private repository contact mechanism when available. Do not place personal, confidential, or security-sensitive information in a public issue.

CONTRIBUTING.md

@@ -1,10 +1,12 @@
 # Contributing to AgentTrace
 
-AgentTrace is an evidence-first observability project. Contributions are welcome, but telemetry claims must be grounded in something the supported harness actually exposes.
+Thanks for helping improve AgentTrace. Contributions are welcome across the trace protocol, storage, collectors, harness adapters, replay safety, CLI/API, desktop inspector, fixtures, benchmarks, documentation, and privacy tooling.
+
+AgentTrace has one non-negotiable rule: **never fabricate telemetry**.
 
 ## Development setup
 
-The core workspace requires Rust 1.85 or newer. The desktop Tauri shell is intentionally a separate workspace and currently requires Rust 1.90 or newer plus Node.js 24.
+The Rust workspace requires Rust 1.85+.
 
 ```bash
 cargo fmt --all -- --check
@@ -13,41 +15,33 @@ cargo test --workspace --all-features
 cargo check --workspace --all-targets
 ```
 
-For the desktop web layer:
+For the desktop inspector:
 
 ```bash
 cd apps/desktop
 npm install
 npm run build
 ```
 
-For the Tauri shell:
-
-```bash
-cargo check --manifest-path apps/desktop/src-tauri/Cargo.toml
-```
-
-## Adapter rules
+See `docs/testing.md` for the full validation matrix.
 
-Every adapter change must preserve the telemetry truth model:
+## Design rules
 
-- `native` means the value came directly from the harness or a documented integration surface.
-- `inferred` means AgentTrace observed a side effect and documents the inference rule.
-- `derived` means AgentTrace deterministically calculated the value from recorded evidence.
-- `unavailable` means the harness does not expose the information reliably enough to claim it.
+1. Every normalized claim must be `native`, `inferred`, `derived`, or `unavailable` with evidence for that provenance.
+2. Missing telemetry stays unavailable; do not infer richer semantics just to make adapters look uniform.
+3. Preserve raw upstream records where it is safe and useful so normalization can improve later.
+4. Protocol-breaking changes require a schema version change and migration/documentation updates.
+5. New harness behavior must be backed by upstream source or official documentation. Do not invent flags, event fields, hooks, or headless modes.
+6. Replay stays dry-run-first and exact-allowlisted. Security boundaries must not be weakened for convenience.
+7. Redaction and local-first defaults are product behavior, not optional polish.
+8. Add contract fixtures/tests for adapter capability claims and negative/unavailable cases.
 
-Do not fill gaps by guessing. Do not label inferred data as native. Do not depend on private or undocumented APIs when a stable public mechanism exists.
+## Harness adapters
 
-When adding or changing a harness integration, include an upstream reference in `docs/research/reference-adapters.md` or `docs/harnesses.md`, plus a small sanitized fixture whenever the upstream format can be represented safely.
-
-## Fixtures
-
-Fixtures must not contain real API keys, user prompts, customer repositories, private file paths, credentials, or proprietary source code. Prefer minimal synthetic records that exercise one protocol behavior at a time.
-
-## Security-sensitive changes
-
-Changes to redaction, replay, process execution, raw-source retention, path handling, or remote binding deserve explicit tests for the failure mode being changed. Replay must remain dry-run-first and must never silently broaden its execution allowlist.
+Document the official upstream repository, supported versions, integration mode, event source, authentication assumptions, capabilities, and known limitations. Update `docs/harnesses.md` and the adapter contract fixtures in the same PR.
 
 ## Pull requests
 
-Keep commits reviewable and explain the evidence behind any new telemetry capability. PRs should state which harnesses and operating systems were tested and whether a capability is native, inferred, derived, or unavailable.
+Keep PRs focused. Explain the telemetry/provenance impact, tests run, privacy/security implications, and any schema or compatibility changes. Performance-sensitive changes should include benchmark notes where practical.
+
+By contributing, you agree to follow `CODE_OF_CONDUCT.md` and the Apache-2.0 license terms.

SECURITY.md

@@ -1,23 +1,23 @@
 # Security Policy
 
-AgentTrace records command output, file activity, model/tool metadata, and raw harness records when available. That makes secret handling and local execution boundaries part of the product's security model, not optional polish.
+AgentTrace records and replays developer-tool activity, so traces may contain source code, commands, paths, prompts, tool payloads, and other sensitive engineering data.
 
 ## Reporting a vulnerability
 
-Do not publish exploit details, credentials, or sensitive trace data in a public issue.
+Do not publish exploit details, credentials, sensitive traces, replay bypasses, redaction bypasses, or remote-access weaknesses in a public issue.
 
-Use GitHub's private vulnerability reporting or Security Advisory flow for this repository when it is available. If private reporting is unavailable, open a public issue containing only a request for a private maintainer contact and enough non-sensitive context to route the report. Do not include reproduction secrets or exploit payloads there.
+If GitHub private vulnerability reporting is enabled, use **Security → Report a vulnerability**. Otherwise, open a minimal non-sensitive issue requesting a private reporting channel.
 
-Please include the affected AgentTrace version or commit, operating system, relevant harness, attack preconditions, and a minimal reproduction that does not contain real credentials or proprietary source code.
+Include the affected commit/version, operating system, minimal reproduction, impact, and whether the issue can expose trace contents, local files, credentials, execute unapproved commands, or bypass loopback/redaction protections.
 
 ## Security boundaries
 
-AgentTrace redacts known secret patterns and sensitive JSON fields before normal persistence paths. Environment capture is deny-by-default. Raw records can still contain unexpected sensitive material, so they should be treated as local sensitive data.
+- No automatic trace upload exists; storage is local-first.
+- Environment capture is deny-by-default and must not indiscriminately persist secrets.
+- Redaction is applied before normal persistence and again on read/export surfaces.
+- The local API binds to loopback by default; non-loopback binding requires explicit opt-in.
+- Replay is dry-run-first and requires explicit execution plus an exact recorded command/sequence allowlist.
+- Replay's temporary Git worktree protects repository state but is **not an operating-system sandbox**.
+- Raw payloads can still contain sensitive information; users should review traces before sharing them.
 
-Replay is dry-run-first and requires an explicit allowlist. Replay uses a detached Git worktree and a scrubbed environment, but it is **not an operating-system sandbox**. An allowlisted command still executes with the current user's OS permissions and can access resources outside the worktree if the command itself does so.
-
-The local API binds to loopback by default. Binding to a non-loopback address requires an explicit opt-in and should only be done behind an appropriate trusted network boundary.
-
-## Supported versions
-
-AgentTrace is pre-1.0. Security fixes are applied to the current development line; older snapshots are not guaranteed to receive backports until a stable support policy is published.
+Changes to redaction, replay, API binding, artifact handling, or credential scrubbing should include focused regression tests and relevant documentation updates.

SUPPORT.md

@@ -0,0 +1,30 @@
+# Support
+
+AgentTrace is a pre-1.0 open-source project. Community support is best-effort; there is no guaranteed response time or commercial SLA.
+
+## Before opening an issue
+
+Check the README and relevant documents under `docs/`, then run:
+
+```bash
+agenttrace doctor
+agenttrace harnesses
+```
+
+For harness-specific problems, include the harness name/version and `agenttrace capabilities <id>` output when safe to share.
+
+## Bugs
+
+Use the bug-report issue form. Include the AgentTrace commit/version, OS, Rust version, harness version/integration mode, the smallest reproducible trace or fixture, and sanitized logs. Never attach credentials, private source, or an unsanitized trace unintentionally.
+
+## Feature requests
+
+Use the feature-request form. Describe the debugging/observability problem first. For new telemetry, explain which upstream surface exposes it and what provenance level it should have.
+
+## Security
+
+Do not report vulnerabilities through a normal issue. Follow `SECURITY.md`.
+
+## Questions
+
+Focused usage questions are welcome as GitHub issues when the README/docs do not already answer them. Keep one problem per issue so answers remain searchable.