From 03f9315127f7683296806fbef44b273b2cf32a5f Mon Sep 17 00:00:00 2001
From: cachetronaut <159639410+cachetronaut@users.noreply.github.com>
Date: Fri, 5 Jun 2026 14:41:31 -0400
Subject: [PATCH] add public readme metadata [skip release]

---
 .github/workflows/ci.yml           |  4 +++
 .github/workflows/npm-release.yml  |  2 ++
 .github/workflows/pypi-release.yml |  2 ++
 .gitignore                         |  2 +-
 README.md                          | 45 ++++++++++++++++++++++++++++++
 py/README.md                       |  1 +
 py/pyproject.toml                  |  6 ++++
 ts/README.md                       |  1 +
 8 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 README.md
 create mode 120000 py/README.md
 create mode 120000 ts/README.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 8748ef5..fef0f46 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,6 +39,10 @@ jobs:
         if: hashFiles('ts/package.json') != ''
         working-directory: ts
         run: pnpm build
+      - name: Prepare TypeScript package README
+        if: hashFiles('ts/package.json') != ''
+        working-directory: ts
+        run: rm README.md && cp ../README.md README.md
       - name: TypeScript publish dry run
         if: hashFiles('ts/package.json') != ''
         working-directory: ts
diff --git a/.github/workflows/npm-release.yml b/.github/workflows/npm-release.yml
index 7db84a0..87246e3 100644
--- a/.github/workflows/npm-release.yml
+++ b/.github/workflows/npm-release.yml
@@ -41,6 +41,8 @@ jobs:
         run: pnpm verify
       - name: Build
         run: pnpm build
+      - name: Prepare package README
+        run: rm README.md && cp ../README.md README.md
       - name: Read package metadata
         id: package
         run: |
diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml
index 81f95ce..d0bb2ef 100644
--- a/.github/workflows/pypi-release.yml
+++ b/.github/workflows/pypi-release.yml
@@ -39,6 +39,8 @@ jobs:
         run: uv run --with ty ty check
       - name: Test
         run: uv run --with pytest --with pytest-asyncio python -m pytest
+      - name: Prepare package README
+        run: rm README.md && cp ../README.md README.md
       - name: Build distribution
         run: uv build
       - name: Read package metadata
diff --git a/.gitignore b/.gitignore
index 80f885b..81d4bc6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -14,9 +14,9 @@ __pycache__/
 *.py[cod]
 .legacy-git/
 .pnpm-store/
-/README.md
 /PRODUCT.md
 /STATUS.md
 /docs/plan/
 /PLANNING/
 NAME.md
+
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3321639
--- /dev/null
+++ b/README.md
@@ -0,0 +1,45 @@
+# Grantz
+
+Scoped, signed, monotonically attenuable delegation tokens for headless agent and tool runs.
+
+This repository contains the TypeScript and Python implementations for the Grantz primitive. The shared repository keeps the public contract, fixtures, and release history aligned across both languages.
+
+## Packages
+
+- npm: `grantz`
+- PyPI: `grantz`
+
+## Install
+
+```sh
+npm install grantz
+pip install grantz
+```
+
+## Layout
+
+- `ts/` - TypeScript implementation and npm package.
+- `py/` - Python implementation and PyPI package.
+- `fixtures/` - Shared conformance and parity fixtures when the primitive needs them.
+
+## Development
+
+Run TypeScript checks from `ts/`:
+
+```sh
+pnpm verify
+```
+
+Run Python checks from `py/`:
+
+```sh
+uv sync --dev
+uv run --with ruff ruff check .
+uv run --with ruff ruff format --check .
+uv run --with ty ty check
+uv run --with pytest --with pytest-asyncio python -m pytest
+```
+
+## License
+
+MIT
diff --git a/py/README.md b/py/README.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/py/README.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file
diff --git a/py/pyproject.toml b/py/pyproject.toml
index 5bb0473..235ba1c 100644
--- a/py/pyproject.toml
+++ b/py/pyproject.toml
@@ -2,10 +2,16 @@
 name = "grantz"
 version = "0.0.0"
 description = "Scoped, signed, monotonically attenuable delegation tokens."
+readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "MIT" }
 dependencies = ["cryptography>=42", "psycopg[binary]>=3.2", "psycopg-pool>=3.2"]
 
+[project.urls]
+Homepage = "https://github.com/cachetronaut/grantz"
+Repository = "https://github.com/cachetronaut/grantz"
+Issues = "https://github.com/cachetronaut/grantz/issues"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
diff --git a/ts/README.md b/ts/README.md
new file mode 120000
index 0000000..32d46ee
--- /dev/null
+++ b/ts/README.md
@@ -0,0 +1 @@
+../README.md
\ No newline at end of file