From c3950b61e621a8b655f01371b61dc3962928edda Mon Sep 17 00:00:00 2001
From: cachetronaut <159639410+cachetronaut@users.noreply.github.com>
Date: Fri, 5 Jun 2026 15:14:48 -0400
Subject: [PATCH] separate product and package readmes [skip release]

---
 .github/workflows/ci.yml           |  4 ----
 .github/workflows/npm-release.yml  |  2 --
 .github/workflows/pypi-release.yml |  2 --
 README.md                          | 30 +++++---------------------
 py/README.md                       | 34 +++++++++++++++++++++++++++++-
 ts/README.md                       | 26 ++++++++++++++++++++++-
 6 files changed, 63 insertions(+), 35 deletions(-)
 mode change 120000 => 100644 py/README.md
 mode change 120000 => 100644 ts/README.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fef0f46..8748ef5 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -39,10 +39,6 @@ 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 87246e3..7db84a0 100644
--- a/.github/workflows/npm-release.yml
+++ b/.github/workflows/npm-release.yml
@@ -41,8 +41,6 @@ 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 d0bb2ef..81f95ce 100644
--- a/.github/workflows/pypi-release.yml
+++ b/.github/workflows/pypi-release.yml
@@ -39,8 +39,6 @@ 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/README.md b/README.md
index 3321639..15e23af 100644
--- a/README.md
+++ b/README.md
@@ -2,43 +2,23 @@
 
 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.
+Grantz is a primitive with TypeScript and Python implementations maintained in one public repository. The shared repo keeps the public contract, fixtures, issues, and release history aligned across languages.
 
 ## Packages
 
 - npm: `grantz`
 - PyPI: `grantz`
 
-## Install
-
-```sh
-npm install grantz
-pip install grantz
-```
-
-## Layout
+## Repository 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/`:
+## Package Documentation
 
-```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
-```
+- TypeScript package notes: [ts/README.md](ts/README.md)
+- Python package notes: [py/README.md](py/README.md)
 
 ## License
 
diff --git a/py/README.md b/py/README.md
deleted file mode 120000
index 32d46ee..0000000
--- a/py/README.md
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
diff --git a/py/README.md b/py/README.md
new file mode 100644
index 0000000..52292be
--- /dev/null
+++ b/py/README.md
@@ -0,0 +1,33 @@
+# grantz
+
+Python implementation of Grantz.
+
+For product-level context, shared contracts, and cross-language repository information, see the public repository: https://github.com/cachetronaut/grantz.
+
+## Install
+
+```sh
+pip install grantz
+```
+
+## Import
+
+```python
+import grantz
+```
+
+## Development
+
+Run 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/ts/README.md b/ts/README.md
deleted file mode 120000
index 32d46ee..0000000
--- a/ts/README.md
+++ /dev/null
@@ -1 +0,0 @@
-../README.md
\ No newline at end of file
diff --git a/ts/README.md b/ts/README.md
new file mode 100644
index 0000000..7ae9ca6
--- /dev/null
+++ b/ts/README.md
@@ -0,0 +1,25 @@
+# grantz
+
+TypeScript implementation of Grantz.
+
+For product-level context, shared contracts, and cross-language repository information, see the public repository: https://github.com/cachetronaut/grantz.
+
+## Install
+
+```sh
+npm install grantz
+```
+
+## Development
+
+Run from `ts/`:
+
+```sh
+pnpm install
+pnpm verify
+pnpm build
+```
+
+## License
+
+MIT