Launch-ready: README hero, community files, examples, release automation

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# wiki-trace is free, MIT, self-hostable. If you'd like to support
+# development, sponsoring on GitHub keeps the project independent.
+github: [OmkarRayAI]

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Something works incorrectly or crashes.
+title: "[bug] "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing. Smaller repros get fixed faster.
+        wiki-trace stores its state as JSONL on disk — pasting the
+        first few lines of `.wikitrace/spans.jsonl` is usually all
+        the diagnostic data we need.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, what did you observe?
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Repro
+      description: Smallest possible script + commands.
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: wikitrace version
+      description: e.g. `0.2.1` or commit SHA
+      placeholder: "0.2.1"
+    validations:
+      required: true
+
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "3.12.3"
+    validations:
+      required: false
+
+  - type: input
+    id: provider
+    attributes:
+      label: Provider / framework (if relevant)
+      placeholder: "openai 1.40 / langchain-core 0.3.5 / crewai 0.70"
+    validations:
+      required: false
+
+  - type: textarea
+    id: span-snippet
+    attributes:
+      label: Relevant spans (if relevant)
+      description: A few lines from `.wikitrace/spans.jsonl` near the issue.
+      render: json
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/OmkarRayAI/wiki-trace/blob/main/SECURITY.md
+    about: Don't open a public issue. See SECURITY.md for the disclosure path.
+  - name: Question or discussion
+    url: https://github.com/OmkarRayAI/wiki-trace/discussions
+    about: For "how do I..." questions, design discussions, or feedback.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature request
+description: Suggest a new capability, integration, or API change.
+title: "[feat] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem are you trying to solve?
+      description: Describe the use case, not the solution.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposal
+      description: |
+        Optional. If you've thought about the API or implementation,
+        share it. Otherwise we'll figure it out together.
+    validations:
+      required: false
+
+  - type: input
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other tools or approaches you've tried.
+    validations:
+      required: false
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: How blocking is this?
+      options:
+        - "Nice to have"
+        - "Would unblock a current project"
+        - "Critical — we can't ship without it"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/integration_request.yml

@@ -0,0 +1,41 @@
+name: Integration request
+description: A framework, provider, or tool you want wiki-trace to support.
+title: "[integration] "
+labels: ["integration"]
+body:
+  - type: input
+    id: name
+    attributes:
+      label: What framework / provider / tool?
+      placeholder: "LlamaIndex, OpenAI Assistants, Haystack, Bedrock, ..."
+    validations:
+      required: true
+
+  - type: input
+    id: link
+    attributes:
+      label: Link to its docs / SDK
+      placeholder: "https://..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: How are you using it today?
+      description: |
+        What does your stack look like? Are you running this in
+        production, eval, or just exploring?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: would-you-help
+    attributes:
+      label: Would you be willing to help test?
+      options:
+        - "Yes — I can run a draft adapter against my real stack"
+        - "Maybe — depends on the time commitment"
+        - "No — just filing the request"
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+<!-- Thanks for contributing. Keep this template short — delete sections
+     that don't apply. -->
+
+## What
+
+A line or two on what this changes.
+
+## Why
+
+The motivation: what problem does this solve, what was broken, what
+new capability does it unlock.
+
+## How to test
+
+```bash
+# the commands a reviewer should run to verify
+```
+
+## Checklist
+
+- [ ] Tests added or updated (or `n/a` with reason)
+- [ ] CI is green on this branch
+- [ ] Docs updated if the public API changed (`README.md`, `CHANGELOG.md`)
+- [ ] No secrets in the diff (run `git diff | grep -i 'sk-\|key=\|token='`)
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code) — only if true.

.github/workflows/publish.yml

@@ -0,0 +1,95 @@
+name: publish
+
+# Publishes to PyPI when a `v*` tag is pushed.
+#
+# Setup (one-time):
+#   1. Create a PyPI account, generate a project-scoped API token at
+#      https://pypi.org/manage/account/token/
+#   2. In repo Settings → Secrets → Actions, add PYPI_API_TOKEN
+#   3. Tag a release: `git tag v0.2.1 && git push origin v0.2.1`
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi:
+    name: PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # Required for PyPI Trusted Publishing (no API token needed once
+      # configured at https://pypi.org/manage/account/publishing/).
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Verify dist
+        run: |
+          python -m pip install twine
+          python -m twine check dist/*
+
+      - name: Publish to PyPI (trusted publishing)
+        # If you've configured Trusted Publishing on PyPI, no token is
+        # needed — id-token: write above is enough.
+        # Otherwise, fall back to API token: comment out this step and
+        # uncomment the one below.
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      # Fallback: API token. Uncomment if Trusted Publishing isn't set up.
+      # - name: Publish to PyPI (API token)
+      #   env:
+      #     TWINE_USERNAME: __token__
+      #     TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      #   run: python -m twine upload dist/*
+
+  npm:
+    name: npm (sdk-js)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: sdk-js
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+          cache: npm
+          cache-dependency-path: sdk-js/package-lock.json
+
+      - name: Install
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -z "$NODE_AUTH_TOKEN" ]; then
+            echo "NPM_TOKEN secret not set — skipping JS publish."
+            exit 0
+          fi
+          # Only publish if the tag's version matches package.json
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "package.json version ($PKG_VERSION) != tag ($TAG_VERSION) — skipping."
+            exit 0
+          fi
+          npm publish --access public

CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to wiki-trace are documented here. The format is
+loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions follow [Semantic Versioning](https://semver.org/) — `0.x` is
+stable enough to use, may break between minor versions until 1.0.
+
+## [Unreleased]
+
+### Added
+- Launch-ready repo polish (see `README.md` for the full pitch)
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, issue/PR
+  templates under `.github/`
+- `examples/` reorganized with one runnable script per integration
+
+## [0.2.1] - 2026-06-05
+
+### Added
+- **Real-API verification via OpenRouter** — first live end-to-end check
+  of `wikitrace.openai.patch` against a real network endpoint. 2 tests
+  pass in <4s on the free tier (#9).
+- OpenRouter integration test path (`tests/integration/test_openrouter_real.py`)
+  and `ci-real-api.yml` GitHub Actions workflow gated on repo secrets (#7, #8).
+- `wikitrace.replay_trace(trace_id, agent=, new_model=)` — re-drive a
+  recorded trace through a different agent and diff outcomes via the
+  existing `RunDiff` infrastructure (#3).
+- `/contribution` dashboard route — surfaces page-contribution as a
+  first-class metric (#3).
+- **Cloud Postgres backend** via `DATABASE_URL` — same `Database` class,
+  asyncpg pool, JSONB round-trip, schema versioning. SQLite remains
+  the zero-dep default (#4).
+- **Self-service cloud signup** at `POST /v1/signup` (no admin key);
+  per-tenant usage metering with daily counters; admin overview at
+  `/v1/admin/usage`; one-command `docker-compose up` deploy (#6).
+- **Cloud-mode dashboard** with `/sign-in` + `/sign-up` flows. Same
+  Next.js binary, multi-tenant when `WIKITRACE_BACKEND=cloud` (#1).
+- **Tests + CI**: 88-test pytest suite, GitHub Actions matrix on Python
+  3.11/3.12 with a Postgres service container, dashboard typecheck job,
+  lint job (#5).
+
+### Changed
+- README: `Tests` section added; pricing table now reflects "self-hosted
+  cloud" tier; integrations table in progress.
+
+### Fixed
+- OpenRouter `<provider>/<model>` price-prefix lookup
+  ([commit 38aa1db](https://github.com/OmkarRayAI/wiki-trace/commit/38aa1db)).
+
+## [0.2.0] - 2026-06-03
+
+### Added
+- **Self-service SaaS surface** — multi-tenant cloud server with API-key
+  auth, tenant isolation, admin CLI, Helicone-compat passthrough.
+- **JS/TS SDK alpha** (Node + browser) — first non-Python language;
+  feature parity at the SDK level.
+- **HTTP ingest server** — multi-language entry point at
+  `python -m wikitrace.ingest_serve`. Helicone async-log compatible.
+- **Provider patches** — `wikitrace.openai.patch()` and
+  `.anthropic.patch()` for sync/async/streaming.
+- **Production runtime** — async batched JSONL writer (~23k spans/sec),
+  rate-limit-aware retry with exponential backoff + jitter, cost
+  budgeting (`wikitrace.budget(usd=10)`).
+- **Eval primitives** — `Dataset`, `run_eval`, `compare_runs`,
+  `load_run`, 16 built-in judges (deterministic + LLM-as-judge),
+  `@wikitrace.eval` decorator.
+- **OpenTelemetry export** — `wikitrace.otel.install()` pipes spans
+  into Phoenix / Datadog / Honeycomb / any OTLP collector.
+- **Multi-step planner traces** — nested span trees via
+  `wikitrace.session()` + `step()`; LangChain handler emits
+  `tool_call` / `agent_action` / streaming `llm_call` spans.
+- **Decorator API** — `@wikitrace.trace`, `@wikitrace.tool` (sync + async).
+- **Sessions / users / tags** — `wikitrace.session(id=, user=, tags=[])`
+  ambient attribution; contextvars-based, async-safe.
+- **Five framework adapters** — LangChain (production-tested), CrewAI /
+  Google ADK / Agno / OpenAI / Anthropic (mocked-verified).
+- **Helicone-style observability dashboard** — `/requests`, `/sessions`,
+  `/users`, `/properties`, `/evaluators` routes.
+
+## [0.1.0] - 2026-05-31
+
+### Added
+- Initial release — Python SDK (~750 LOC, stdlib-only), Next.js
+  dashboard, LangChain integration, JSONL contract, citation tracking,
+  curated wiki page flow.

CODE_OF_CONDUCT.md

@@ -0,0 +1,26 @@
+# Code of Conduct
+
+We follow the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Short version
+
+- Be kind. Engineers come in all shapes; assume good faith.
+- Critique code, not people. "This is wrong because X" not "you're wrong."
+- No harassment, slurs, sexual attention, doxxing, sustained disruption,
+  or political flame wars in project spaces.
+- If something feels off, flag it. The maintainer is reachable at
+  **omkarrayai@gmail.com**.
+
+## Scope
+
+Applies to all project spaces (repo, issues, PRs, discussions, any
+official chat) and to public spaces where someone is representing the
+project.
+
+## Enforcement
+
+Reports go to **omkarrayai@gmail.com**. We respond within 7 days with
+the response we believe is appropriate to the situation, in line with
+the Contributor Covenant's enforcement guidelines.
+
+We will respect the privacy and safety of the reporter.