Separate product and package READMEs

.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

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

.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

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
 

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

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