Release v0.4.0: launch-ready presentation

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Report a defect with a clear repro
+title: "[bug] "
+labels: bug
+assignees: ''
+---
+
+## What happened
+
+A clear description of the behavior you observed.
+
+## What you expected
+
+A clear description of the behavior you expected.
+
+## Minimal reproduction
+
+```python
+# Smallest possible snippet that reproduces the issue.
+# Include any non-default config values.
+```
+
+## Environment
+
+- Temporal Gradient version: (e.g. 0.3.0)
+- Python version: (output of `python --version`)
+- OS:
+- PyYAML installed: yes / no
+
+## Additional context
+
+Stack traces, telemetry packets, or notes about what you tried.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Propose a new capability — lead with the use case
+title: "[feature] "
+labels: enhancement
+assignees: ''
+---
+
+## The use case
+
+What are you trying to do? Describe the situation, not the proposed
+solution. "I need to do X and the current API forces Y" is more useful
+than "please add method Z."
+
+## Why the current API doesn't fit
+
+What did you try? Where did it break down?
+
+## A sketch of what might work
+
+Optional. If you have a concrete API in mind, show it. If not, leave
+this blank — the maintainer can propose a shape that fits.
+
+```python
+# Example usage (rough is fine)
+```
+
+## Scope check
+
+- Does this fit within the project's stated scope? See [CONTRIBUTING.md](../../CONTRIBUTING.md#whats-in-scope).
+- Does it require a new runtime dependency? (The core package is zero-dependency by design.)
+- Does it change the telemetry packet schema?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,29 @@
+## What this PR does
+
+A short description of the change.
+
+## Why
+
+The motivation. If this fixes a bug, link the issue. If it adds a
+capability, describe the use case.
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature (non-breaking)
+- [ ] Breaking change (telemetry schema, public API, or default behavior)
+- [ ] Documentation only
+- [ ] Refactor / internal cleanup
+
+## Checklist
+
+- [ ] `pytest` passes locally on Python 3.10+
+- [ ] New behavior is covered by tests
+- [ ] Public API changes are reflected in [`docs/architecture.md`](../docs/architecture.md)
+- [ ] [`CHANGELOG.md`](../CHANGELOG.md) updated under `[Unreleased]` if user-visible
+- [ ] No new runtime dependencies added to the core package (or discussed first)
+
+## Notes for the reviewer
+
+Anything non-obvious: trade-offs, things you considered and rejected,
+follow-ups that should be separate PRs.

.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/temporal-gradient/
+    permissions:
+      id-token: write  # trusted publishing (OIDC) — no API token needed
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v0.4.0 — Launch-ready presentation
+
+**Release focus:** make the project legible to first-time visitors —
+no code changes to the engine, but a materially different surface for
+anyone landing on the repo.
+
+### Added
+
+- `examples/showcase.py` — deterministic 30-second demo. Same 20-event
+  stream fed to a naive LRU and to Temporal Gradient. The naive system
+  evicts the critical signal with routine traffic; Temporal Gradient
+  retains it as the sole survivor.
+- `CONTRIBUTING.md` — scope/out-of-scope, dev setup, PR expectations.
+- `CODE_OF_CONDUCT.md` — Contributor Covenant 2.1.
+- `.github/ISSUE_TEMPLATE/bug_report.md`,
+  `.github/ISSUE_TEMPLATE/feature_request.md`,
+  `.github/PULL_REQUEST_TEMPLATE.md`.
+
+### Changed
+
+- README rewritten to lead with a tagline ("An engine that gives
+  software a sense of its own time"), a motivation paragraph, and the
+  showcase output above the fold. Adds CI / license / Python / status
+  badges, the ASCII data-flow diagram inline, a sample telemetry packet,
+  a "What this is not" callout, and a comparison table vs. rate
+  limiters, LRU, and vector databases.
+
+### No engine changes
+
+The clock, salience, memory, policies, and telemetry modules are
+unchanged from v0.3.0. All 166 tests pass. No migration required.
+
 ## v0.3.0 — Cleanup & simplification
 
 **Release focus:** remove accumulated compatibility cruft, consolidate

CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free
+experience for everyone, regardless of age, body size, visible or
+invisible disability, ethnicity, sex characteristics, gender identity
+and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by mistakes,
+  and learning from the experience
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political
+  attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may
+be reported by opening a private issue, or contacting the project
+maintainer directly via the email listed on the GitHub profile of the
+repository owner.
+
+All complaints will be reviewed and investigated promptly and fairly.
+The maintainer is obligated to respect the privacy and security of the
+reporter.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to Temporal Gradient
+
+Thanks for your interest. This project is small, opinionated, and built
+around a specific mathematical model. Contributions are welcome — please
+read this short guide before opening a PR.
+
+## What's in scope
+
+- New salience scorers (novelty or value implementations behind the
+  existing interfaces in [`temporal_gradient/contracts/`](temporal_gradient/contracts/))
+- Adapters for real event sources (queue consumers, log tailers, webhook
+  receivers) — likely as separate examples rather than core
+- Persistence backends for the memory store
+- Performance work, additional test coverage, documentation improvements
+- Bug fixes (with a failing test that demonstrates the bug)
+
+## What's out of scope
+
+- Claims about cognition, consciousness, or subjective time experience
+  — see [`docs/safety.md`](docs/safety.md). The framework is dynamics,
+  not theory of mind.
+- Renaming or restructuring core state variables (Ψ, τ, S) — these are
+  intentionally fixed and load-bearing across docs.
+- Breaking changes to the telemetry packet schema without a SCHEMA_VERSION
+  bump and a migration note.
+
+## Before you open a PR
+
+1. **Run the tests.** `pytest` should pass on Python 3.10, 3.11, and 3.12.
+2. **Add a test** for any behavioral change. The test suite is the
+   contract — see [`tests/`](tests/) for style.
+3. **Keep the diff focused.** One concern per PR. Refactors separate from
+   features separate from fixes.
+4. **Update docs** if you change a public interface or default. The
+   architecture diagram and packet schema in [`docs/architecture.md`](docs/architecture.md)
+   must stay in sync with the code.
+
+## Development setup
+
+```bash
+git clone https://github.com/WhatsYourWhy/The-Temporal-Gradient
+cd The-Temporal-Gradient
+pip install -e ".[dev]"
+pytest
+```
+
+## Filing an issue
+
+Use the provided templates. For bugs, include:
+- Python version
+- Minimal reproduction
+- Expected vs. actual behavior
+
+For features, lead with the use case, not the implementation. "I need
+to do X and the current API forces Y" is more useful than "please add
+method Z."
+
+## Style
+
+- No new runtime dependencies without discussion. The core package is
+  zero-dependency by design.
+- Standard `black`-compatible formatting. No enforced linter, but match
+  the surrounding code.
+- Type hints on new public functions.
+- Comments only when the *why* is non-obvious. Don't narrate the *what*.
+
+## License
+
+By contributing, you agree your contributions are licensed under the
+project's [MIT license](LICENSE).