fix(ci): wasm nightly, python trusted publishing, better README

typescript-ci.yml:
- dtolnay/rust-toolchain@nightly (wasm-pack needs --artifact-dir = nightly)
- remove --out-dir flag (wasm-pack defaults to pkg/)
- --scope promptexecution so package publishes as @promptexecution/tomllm
- gate npm publish on v* tags

python-ci.yml:
- replace deprecated maturin upload with pypa/gh-action-pypi-publish
- PyPI Trusted Publishing (OIDC, no token secret required)
- gate PyPI publish on v* tags

Cargo.toml: updated description + documentation URL
pyproject.toml: added version, readme, keywords, classifiers, project URLs
README.md: full rewrite — business description, no project-specific jargon,
  annotation prefix table, Rust/Python/TS usage examples, tail-map format docs
src/lib.rs: updated crate-level doc comment to match

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: elasticdotventures

.github/workflows/python-ci.yml

@@ -3,18 +3,17 @@ name: Python CI
 on:
   push:
     branches: [main]
+    tags: ["v*"]
   pull_request:
     branches: [main]
 
 jobs:
   build:
+    name: Build wheels (linux x86_64)
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - name: Build wheel
+      - name: Build manylinux wheel
         uses: PyO3/maturin-action@v1
         with:
           command: build
@@ -27,18 +26,21 @@ jobs:
           path: dist/
 
   publish-pypi:
+    name: Publish to PyPI
     needs: build
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
     steps:
       - uses: actions/download-artifact@v4
         with:
           name: wheels-linux
           path: dist/
-      - name: Publish to PyPI
-        uses: PyO3/maturin-action@v1
+      - name: Publish
+        # Trusted Publishing: no token needed once project is registered on PyPI
+        # with this repo as a trusted publisher (https://pypi.org/manage/account/publishing/)
+        # Fallback: set PYPI_API_TOKEN secret and use password auth below
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          command: upload
-          args: --non-interactive --skip-existing dist/*
-        env:
-          MATURIN_PYPI_TOKEN: ${{ secrets.MATURIN_PYPI_TOKEN }}
+          skip-existing: true

.github/workflows/typescript-ci.yml

@@ -3,6 +3,7 @@ name: TypeScript / WASM CI
 on:
   push:
     branches: [main]
+    tags: ["v*"]
   pull_request:
     branches: [main]
 
@@ -11,38 +12,37 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions-rs/toolchain@v1
+      # wasm-pack internally passes --artifact-dir to cargo, which requires nightly
+      - uses: dtolnay/rust-toolchain@nightly
         with:
-          toolchain: stable
-          override: true
-          target: wasm32-unknown-unknown
+          targets: wasm32-unknown-unknown
       - name: Install wasm-pack
         run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
-      - name: Build WASM (bundler)
-        run: wasm-pack build --target bundler --features wasm --out-dir pkg
-      - name: Build WASM (nodejs)
-        run: wasm-pack build --target nodejs --features wasm --out-dir pkg-nodejs
-      - name: Upload WASM artifacts
+      - name: Build WASM (bundler target)
+        run: wasm-pack build --target bundler --features wasm --scope promptexecution
+      - name: Upload WASM artifact
         uses: actions/upload-artifact@v4
         with:
           name: wasm-pkg
           path: pkg/
 
   publish-npm:
+    name: Publish to npm
     needs: wasm-build
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          registry-url: "https://registry.npmjs.org"
       - uses: actions/download-artifact@v4
         with:
           name: wasm-pkg
           path: pkg/
-      - name: Publish to npm
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+      - name: Publish
+        # wasm-pack generates pkg/package.json with @promptexecution/tomllm name
         run: npm publish --access public
+        working-directory: pkg/
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

Cargo.toml

@@ -2,10 +2,11 @@
 name = "tomllm"
 version = "0.1.0"
 edition = "2024"
-description = "TOML + LLM comment conventions: tribal knowledge in #comments, stripped for data pipelines"
+description = "Structured TOML annotations for AI-augmented applications — annotate config for LLMs, strip for pipelines"
 license = "MIT"
 repository = "https://github.com/PromptExecution/tomllm"
-keywords = ["toml", "llm", "agent", "config", "annotations"]
+documentation = "https://docs.rs/tomllm"
+keywords = ["toml", "llm", "ai", "config", "annotations"]
 categories = ["parsing", "config", "text-processing"]
 readme = "README.md"
 

README.md

@@ -1,65 +1,128 @@
 # tomllm
 
-TOML + LLM comment conventions: tribal knowledge in `#comments`, stripped for data pipelines.
+**Structured TOML annotations for AI-augmented applications.**
 
-## Overview
+`tomllm` extends standard TOML with a lightweight comment convention that lets configuration files carry machine-readable documentation alongside their values. Annotation comments survive in source for human and LLM readers; a single call strips them for clean downstream serialization.
 
-`.tomllm` files are **valid TOML** with enriched `#` comment semantics:
+---
 
-- Comments associate with the next key-value pair or section header
-- Special prefixes encode tribal knowledge: `# 🤓`, `# @tribal:`, `# @example:`, `# @requires:`
-- Tail-map block (last ≤10 lines): fast executive agent scanning without full context load
-- Comments are FOR agents reading the **source file** as documentation — strip them for downstream pipelines
+## The problem
 
-## Cognitive Tiers
+Configuration files written for LLM agents face a tension: agents need rich context (what does this key mean? what are valid values? what are the gotchas?) but downstream data pipelines need clean, minimal payloads. Embedding that context in comments today means either shipping noisy config to your pipeline or maintaining a separate documentation layer that drifts.
 
-Each `.tomllm` file MAY declare its required cognitive tier in the tail-map:
+## What tomllm does
 
-| Tier | Models | Tasks |
-|------|--------|-------|
-| `sm0l` | qwen2.5-3B, haiku | classify, route, grep, format |
-| `ch0nky` | qwen3-coder (local) | implement, refactor, debug |
-| `frontier` | claude-opus/sonnet | architecture, security, novel design |
+A `.tomllm` file is a **valid TOML file** — any TOML parser reads it normally. `tomllm` adds:
 
-## Example
+**1. Annotation comments** — special prefixes associate structured metadata with the next key:
 
 ```toml
-# @tribal: always use uv pip, never pip install directly
 # @example: uv pip install requests
+# @requires: Python 3.9+, uv installed
+# @deprecated: use poetry instead
 package_manager = "uv"
 
-# b00t:map v1
-# summary: Python toolchain config
-# tags: python, uv
-# tier: sm0l
-# complexity: 2
+# @example: DATABASE_URL=postgres://localhost/mydb
+database_url = "postgres://prod-host/mydb"
+```
+
+**2. Stripping** — one call removes all annotation comments, yielding clean TOML or JSON for pipelines:
+
+```rust
+let doc = TomllmDoc::parse(raw_config)?;
+let clean = doc.strip_for_pipeline(); // annotation-free JSON
 ```
 
+**3. Tail-map** — a structured metadata block at the end of any file enables fast scanning without full parsing:
+
+```toml
+# tomllm:map v1
+# summary: Database connection config for production
+# tags: database, postgres, production
+# tier: ops
+# complexity: 3
+```
+
+Agents can extract the tail-map in microseconds to route, prioritize, or skip files without deserializing their full contents.
+
+---
+
+## Annotation prefixes
+
+| Prefix | Meaning |
+|--------|---------|
+| `# @example:` | Concrete usage example for this key |
+| `# @requires:` | Prerequisites or dependencies |
+| `# @deprecated:` | Deprecation notice with replacement |
+| `# @note:` | Non-obvious behavior or constraint |
+| `# @tribal:` | Institutional knowledge that isn't in the docs |
+
+All annotation lines are stripped by `strip_for_pipeline()`. Plain comments (no prefix) are preserved.
+
+---
+
+## Install
+
+```bash
+# Rust
+cargo add tomllm
+
+# Python
+pip install tomllm
+
+# npm / TypeScript
+npm install @promptexecution/tomllm
+```
+
+---
+
 ## Usage
 
 ### Rust
 
 ```rust
-use tomllm::TomllmDoc;
+use tomllm::{TomllmDoc, MapBlock};
+
+let input = r#"
+# @example: uv pip install requests
+package_manager = "uv"
+
+# tomllm:map v1
+# summary: Python toolchain config
+# tags: python, packaging
+# complexity: 2
+"#;
 
 let doc = TomllmDoc::parse(input)?;
-let clean_json = doc.strip_for_pipeline(); // stripped TOML as JSON
-let tier = doc.cognitive_tier();           // sm0l / ch0nky / frontier
-let map = doc.map_block;                   // Option<MapBlock>
+
+// Strip annotations → clean JSON for pipelines
+let json = doc.strip_for_pipeline();
+
+// Extract tail-map metadata
+if let Some(map) = &doc.map_block {
+    println!("{} | tags: {:?}", map.summary, map.tags);
+}
+
+// Pull all annotations out as structured data
+let annotations = doc.annotations();
 ```
 
-### Python (maturin)
+### Python
 
 ```python
 from tomllm import TomllmDoc, MapBlock
 
 doc = TomllmDoc.parse(text)
-print(doc.cognitive_tier())   # "sm0l"
-print(doc.strip_for_pipeline())  # JSON string
 
+# Clean TOML/JSON for downstream
+clean = doc.strip_for_pipeline()
+
+# Tail-map metadata
 block = MapBlock.from_text(text)
 if block:
-    print(block.summary, block.tier, block.tags)
+    print(block.summary)   # "Python toolchain config"
+    print(block.tags)      # ["python", "packaging"]
+    print(block.complexity) # 2
 ```
 
 ### TypeScript / WASM
@@ -68,41 +131,36 @@ if block:
 import init, { TomllmDoc } from '@promptexecution/tomllm';
 
 await init();
+
 const doc = TomllmDoc.parse(text);
+const clean = doc.strip_for_pipeline();
+const mapBlock = doc.map_block();
 ```
 
-## Install
-
-```bash
-# Rust
-cargo add tomllm
-
-# Python
-pip install tomllm
-
-# npm
-npm install @promptexecution/tomllm
-```
+---
 
 ## Tail-map format
 
+The tail-map is an optional block at the end of any `.tomllm` file (or any TOML file) that provides fast metadata extraction:
+
 ```toml
-# b00t:map v1
-# summary: one-line human+LLM description
+# tomllm:map v1
+# summary: one-line description for humans and agents
 # tags: comma, separated, keywords
-# tier: sm0l|ch0nky|frontier
-# cmds: b00t hive activate inference-qwen3, b00t hive status
+# tier: sm0l | standard | advanced
 # complexity: 1-10
 ```
 
+The `TomllmRegistry` can scan a directory of `.tomllm` files, extract only their tail-maps, and return a sorted/filtered index — useful for capability discovery, configuration routing, or context assembly.
+
+---
+
+## Motivation
+
+This library was extracted from internal tooling at [PromptExecution](https://github.com/PromptExecution) where configuration files are read by both human engineers and LLM agents. The annotation convention emerged from a practical need: agents need context that pipelines don't, and maintaining two versions of every config file is unsustainable.
+
+---
+
 ## License
 
 MIT
-
-<!-- b00t:map v1
-summary: tomllm — TOML + LLM comment conventions crate
-tags: toml, llm, agent, config, annotations, wasm, python
-tier: sm0l
-cmds: cargo test, maturin build --features python, wasm-pack build
-complexity: 3
--->

pyproject.toml

@@ -4,15 +4,30 @@ build-backend = "maturin"
 
 [project]
 name = "tomllm"
+version = "0.1.0"
 requires-python = ">=3.9"
-description = "TOML + LLM comment conventions: tribal knowledge in #comments, stripped for data pipelines"
+description = "Structured TOML annotations for AI-augmented applications"
 license = { text = "MIT" }
+readme = "README.md"
+keywords = ["toml", "llm", "ai", "config", "annotations", "agents"]
 classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
     "Programming Language :: Rust",
-    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Topic :: Software Development :: Libraries",
+    "Topic :: Text Processing :: Markup",
 ]
 
+[project.urls]
+Repository = "https://github.com/PromptExecution/tomllm"
+Issues = "https://github.com/PromptExecution/tomllm/issues"
+
 [tool.maturin]
 features = ["python"]
 module-name = "tomllm"