Documentation refresh for main (docs-only)

CONTRIBUTING.md

@@ -1,140 +1,60 @@
-# Contributing Guidelines
+# Contributing
 
-### Contents
+Trusted Server accepts focused code and documentation contributions. By
+submitting a contribution, you agree that it is licensed under the repository's
+Apache License 2.0.
 
-- [Submitting Pull Requests](#repeat-submitting-pull-requests)
-- [Writing Commit Messages](#memo-writing-commit-messages)
-- [Code Review](#white_check_mark-code-review)
-- [Coding Style](#nail_care-coding-style)
-- [Credits](#pray-credits)
+## Before implementation
 
-## :repeat: Submitting Pull Requests
+Search the issue tracker before opening a new issue. For a substantial change,
+describe the problem, intended behavior, affected adapters, and compatibility
+constraints before investing in an implementation. Do not place credentials or
+non-public vulnerability details in an issue; contact the maintainers privately
+before disclosure.
 
-We **love** pull requests! Before [forking the repo](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) and [creating a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests) for non-trivial changes, it is usually best to first open an issue to discuss the changes, or discuss your intended approach for solving the problem in the comments for an existing issue.
+Read [CLAUDE.md](CLAUDE.md) for repository architecture, target constraints,
+coding conventions, error handling, documentation rules, and commit policy.
+The [project governance document](ProjectGovernance.md) defines decision and
+release responsibilities.
 
-For most contributions, after your first pull request is accepted and merged, you will be [invited to the project](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) and given **push access**. :tada:
+## Make a focused change
 
-_Note: All contributions will be licensed under the project's license._
+- Keep one pull request centered on one coherent outcome.
+- Do not refactor or reformat unrelated code.
+- Add tests for new behavior and regression tests for defects.
+- Keep platform-specific dependencies out of `trusted-server-core`.
+- Use `error-stack` reports for production errors; the Spin entry-point FFI is
+  the sole documented `anyhow` exception.
+- Use fictional example data by default. A real public vendor endpoint requires
+  the exact reviewed exception described in `CLAUDE.md`.
+- Update the canonical guide or crate README when a user-visible contract
+  changes; do not copy volatile matrices into multiple documents.
 
-- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether.
+## Verify
 
-- **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing!
+Run the target-matched checks in [CLAUDE.md](CLAUDE.md#ci-gates), the
+canonical command surface for local and CI verification. [TESTING.md](TESTING.md)
+links focused runbooks without duplicating that matrix.
 
-- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it.
+Keep a pull request in draft while required checks or known changes remain.
+Before requesting review, inspect the complete diff, resolve all failures, and
+state any platform path that could not be exercised.
 
-- **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future.
+## Commits
 
-- **Include test coverage.** Add unit tests or UI tests when possible. Follow existing patterns for implementing tests.
+Write concise, imperative, sentence-case subjects without semantic prefixes or
+bracketed tags. Keep the subject at 50 characters when practical and do not end
+it with a period. Use a wrapped body when the reason, compatibility effect, or
+non-obvious tradeoff is not evident from the diff.
 
-- **Use the repo's default branch.** Branch from and [submit your pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to the repo's default branch. Usually this is `main`, but it could be `dev`, `develop`, or `master`.
+Examples:
 
-- **[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur.
+- `Document Cloudflare startup configuration`
+- `Reject ambiguous integration route records`
 
-- **Keep PR in Draft** until ready for review. When it is ready, assign the PR to yourself and request at least one reviewer.
+## Review
 
-- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it.
-
-- When writing comments, use properly constructed sentences, including punctuation.
-
-- Use spaces, not tabs.
-
-## :memo: Writing Commit Messages
-
-Please [write a great commit message](https://chris.beams.io/posts/git-commit/).
-
-1. Separate subject from body with a blank line
-1. Limit the subject line to 50 characters
-1. Use sentence case (capitalize the first word)
-1. Do not end the subject line with a period
-1. Use the imperative mood in the subject line (example: "Fix networking issue")
-1. Wrap the body at about 72 characters
-1. Use the body to explain **why**, _not what and how_ (the code shows that!)
-1. Do not use semantic prefixes or tags (examples: `fix:`, `feat:`, `[Docs]`)
-1. Keep PR state out of commit messages; use GitHub Draft PRs instead
-
-```
-Short summary of changes in 50 chars or less
-
-Add a more detailed explanation here, if necessary. Possibly give
-some background about the issue being fixed, etc. The body of the
-commit message can be several paragraphs. Further paragraphs come
-after blank lines and please do proper word-wrap.
-
-Wrap it to about 72 characters or so. In some contexts,
-the first line is treated as the subject of the commit and the
-rest of the text as the body. The blank line separating the summary
-from the body is critical (unless you omit the body entirely);
-various tools like `log`, `shortlog` and `rebase` can get confused
-if you run the two together.
-
-Explain the problem that this commit is solving. Focus on why you
-are making this change as opposed to how or what. The code explains
-how or what. Reviewers and your future self can read the patch,
-but might not understand why a particular solution was implemented.
-Are there side effects or other unintuitive consequences of this
-change? Here's the place to explain them.
-
- - Bullet points are okay, too
-
- - A hyphen or asterisk should be used for the bullet, preceded
-   by a single space, with blank lines in between
-
-Note the fixed or relevant GitHub issues at the end:
-
-Resolves: #123
-See also: #456, #789
-```
-
-## :white_check_mark: Code Review
-
-- **Review the code, not the author.** Look for and suggest improvements without disparaging or insulting the author. Provide actionable feedback and explain your reasoning.
-
-- **You are not your code.** When your code is critiqued, questioned, or constructively criticized, remember that you are not your code. Do not take code review personally.
-
-- **Always do your best.** No one writes bugs on purpose. Do your best, and learn from your mistakes.
-
-- Kindly note any violations to the guidelines specified in this document.
-
-- **Use CREG (Code Review Emoji Guide)** to give the reviewee added context and clarity to follow up on code review.
-
-### Emoji Legend
-
-|        |             `:code:`             | Meaning                                                                                                                                                                                                                                         |
-| :----: | :------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 😃👍💯 |    `:smiley:` `:+1:` `:100:`     | I like this... <br /><br /> ...and I want the author to know it! This is a way to highlight positive parts of a code review.                                                                                                                    |
-|   🔧   |            `:wrench:`            | I think this needs to be changed. <br /><br />This is a concern or suggested change/refactor that I feel is worth addressing.                                                                                                                   |
-|   ❓   |           `:question:`           | I have a question. <br /><br /> This should be a fully formed question with sufficient information and context that requires a response.                                                                                                        |
-|  🤔💭  | `:thinking:` `:thought_balloon:` | Let me think out loud here for a minute. <br /><br /> I might express concern, suggest an alternative solution, or walk through the code in my own words to make sure I understand.                                                             |
-|   🌱   |           `:seedling:`           | Planting a seed for future. <br /><br /> An observation or suggestion that is not a change request, but may have larger implications. Generally something to keep in mind for the future.                                                       |
-|   📝   |             `:memo:`             | This is an explanatory note, fun fact, or relevant commentary that does not require any action.                                                                                                                                                 |
-|   ⛏    |             `:pick:`             | This is a nitpick. <br /><br /> This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter |
-|   ♻️   |           `:recycle:`            | Suggestion for refactoring. <br /><br /> Should include enough context to be actionable and not be considered a nitpick.                                                                                                                        |
-|   🏕   |           `:camping:`            | Here is an opportunity, not directly related to your changes, for us to leave the campground [code] cleaner than we found it.                                                                                                                   |
-|   📌   |           `:pushpin:`            | This is a concern that is _out of scope_ and should be staged appropriately for follow up.                                                                                                                                                      |
-
-## :nail_care: Coding Style
-
-Consistency is the most important. Following the existing Rust style, formatting, and naming conventions of the file you are modifying and of the overall project. Failure to do so will result in a prolonged review process that has to focus on updating the superficial aspects of your code, rather than improving its functionality and performance.
-
-Style and format will be enforced with a linter when PR is created.
-
-## :warning: Error Handling
-
-We use [error-stack](https://docs.rs/error-stack/latest/error_stack/) for error handling to provide rich context and traceability.
-
-### Guidelines
-
-1. **Use `Report<E>`**: Public functions should generally return `Result<T, Report<TrustedServerError>>`.
-2. **Context**: Use `.change_context(TrustedServerError::Variant)` to wrap errors and provide semantic meaning.
-   ```rust
-   // Good
-   file.read_to_string(&mut content)
-       .change_context(TrustedServerError::Configuration { message: "Failed to read config".into() })?;
-   ```
-3. **Attachments**: Use `.attach_printable("additional info")` to add debugging context without changing the error variant.
-4. **Consistency**: Avoid returning bare `TrustedServerError` unless absolutely necessary (e.g. implementing traits). Wrap them in `Report::new()`.
-
-## :pray: Credits
-
-- https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md
-- https://github.com/erikthedeveloper/code-review-emoji-guide
+Review the change, not the author. Tie blocking feedback to a correctness,
+security, compatibility, maintainability, or documented-requirement concern.
+Mark optional improvements as non-blocking and move unrelated work to a
+separate issue.

crates/trusted-server-adapter-axum/README.md

@@ -0,0 +1,25 @@
+# trusted-server-adapter-axum
+
+Native development adapter for Trusted Server. It runs the shared application
+through Axum on the host, without an edge simulator, and is not a production
+deployment target.
+
+The crate owns Axum route registration, middleware, outbound HTTP through
+`reqwest`, and environment-backed platform services. Its route surface follows
+the shared core contract, but request-time KV operations are unavailable and a
+startup error makes every route, including `/health`, return 500. Application
+configuration reaches the process through the documented environment bridge;
+the local EdgeZero config-store file is not read directly.
+
+Build and test from the repository root:
+
+```bash
+cargo build-axum
+cargo test-axum
+```
+
+Run the isolated first-success check with `./scripts/smoke-axum.sh`. See the
+[Axum development guide](../../docs/guide/axum-dev.md) for its config and
+secret handoff, negative cases, success oracle, and cleanup behavior. Shared
+runtime behavior belongs in
+[`trusted-server-core`](../trusted-server-core/README.md), not this adapter.

crates/trusted-server-adapter-cloudflare/README.md

@@ -0,0 +1,25 @@
+# trusted-server-adapter-cloudflare
+
+Cloudflare Workers adapter for Trusted Server. Production code targets
+`wasm32-unknown-unknown` with the `cloudflare` feature; native builds exist for
+adapter tests and deliberately exclude the Workers entry point.
+
+The crate translates Worker requests and responses, registers the shared
+router, and implements Cloudflare-specific HTTP and secret access. The current
+runtime does not open the KV config value written by `ts config push`; startup
+instead consumes the nested `TRUSTED_SERVER_CONFIG` variable bridge. It also
+has no `/health` route or request-time KV registry and permits one enabled
+auction provider.
+
+Build and test from the repository root:
+
+```bash
+cargo build-cloudflare
+cargo test-cloudflare
+```
+
+Run `./scripts/smoke-cloudflare.sh` for the isolated Wrangler handoff check.
+The [Cloudflare deployment guide](../../docs/guide/cloudflare.md) documents the
+required double encoding, secret bindings, failure cases, and cleanup. Keep
+portable request behavior in
+[`trusted-server-core`](../trusted-server-core/README.md).

crates/trusted-server-adapter-fastly/README.md

@@ -0,0 +1,25 @@
+# trusted-server-adapter-fastly
+
+Production Fastly Compute adapter for Trusted Server, targeting
+`wasm32-wasip1`.
+
+This crate owns the Fastly entry point, dynamic backend construction, edge
+cache behavior, config and secret-store access, EC KV operations, rate limits,
+streaming template assembly, and Fastly-only Tinybird auction emission. Its
+`/health` response is served before application construction, so liveness does
+not prove that configuration loaded. Platform-neutral routing, settings,
+auctions, integrations, and rewrites remain in `trusted-server-core`.
+
+Build and test from the repository root:
+
+```bash
+cargo build-fastly
+cargo test-fastly
+```
+
+The test alias uses Viceroy for the WASM target. Run
+`./scripts/smoke-fastly.sh` for the isolated config-store, secret-store, and
+publisher-response handoff. See the
+[Fastly deployment guide](../../docs/guide/fastly.md) for provisioning and
+runtime boundaries and [Auction Telemetry](../../docs/guide/telemetry.md) for
+the Fastly-only telemetry path.

crates/trusted-server-adapter-spin/README.md

@@ -0,0 +1,23 @@
+# trusted-server-adapter-spin
+
+Experimental Fermyon Spin adapter for Trusted Server. The component targets
+`wasm32-wasip1` with the `spin` feature; native builds exercise route and
+platform tests.
+
+The crate maps Spin HTTP, variables, and the `default` key-value store into the
+shared runtime. Startup failures install a restricted 503 router that keeps
+`/health` live. The adapter permits one enabled auction provider. Request-time
+KV services beyond startup config loading remain unavailable. Its entry point
+uses `anyhow::Result` only because the EdgeZero Spin FFI requires that type.
+
+Build and test from the repository root:
+
+```bash
+cargo build --package trusted-server-adapter-spin --target wasm32-wasip1 --features spin --release
+cargo test-spin
+```
+
+Run `./scripts/smoke-spin.sh` for the isolated config, encoded-secret, failure,
+and publisher-response checks. See the
+[Spin deployment guide](../../docs/guide/spin.md) for the exact local-store
+mapping and operational limitations.

crates/trusted-server-cli/README.md

@@ -0,0 +1,23 @@
+# trusted-server-cli
+
+Host-target operator CLI for Trusted Server. The installed binary is `ts`.
+
+The CLI validates and publishes application configuration through EdgeZero,
+delegates platform lifecycle commands, audits public pages and ad-template
+configuration, and builds external Prebid artifacts. It is not part of any
+adapter WASM artifact. Most commands support Linux and macOS; the production-
+hostname development proxy and local CA commands are macOS-only.
+
+Install and test from the repository root:
+
+```bash
+cargo install-cli
+./scripts/test-cli.sh
+```
+
+The test script selects and, when necessary, installs the host Rust target,
+runs the CLI suite, and executes the ignored browser-backed audit fixtures
+serially. See the [CLI guide](../../docs/guide/cli.md) for the generated
+two-platform command inventory and the
+[EdgeZero guide](../../docs/guide/edgezero.md) for configuration lifecycle and
+store semantics.