Add public README metadata

.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

.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: |

.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

.gitignore

@@ -14,9 +14,9 @@ __pycache__/
 *.py[cod]
 .legacy-git/
 .pnpm-store/
-/README.md
 /PRODUCT.md
 /STATUS.md
 /docs/plan/
 /PLANNING/
 NAME.md
+

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

py/README.md

@@ -0,0 +1 @@
+../README.md

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"

ts/README.md

@@ -0,0 +1 @@
+../README.md