@mean-weasel/lineage 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.4
+
+- Implement target-scoped agent claims for lineage and content-post agent writes, including claim lifecycle CLI/API commands, heartbeat/release/revoke/transfer controls, and token-redacted read APIs.
+- Add claim-aware handoff packets, workspace/content occupancy badges, and a read-only Agents view so humans can see active, idle, stale, and closed claims without exposing raw tokens.
+- Enforce matching claim tokens for claimed lineage/content mutations and document the `LINEAGE_CLAIM_TOKEN` operator flow, including rare `project_channel` ownership.
+
 ## 0.1.3
 
 - Add a managed Swissifier rich-demo media download flow that verifies the release archive and restored PNG checksums before loading the demo.

package/README.md

@@ -40,6 +40,40 @@ By default, `lineage start` listens on `lineage.localhost:5197` and stores SQLit
 lineage start --port 6123 --db ~/.lineage/lineage.sqlite
 ```
 
+## Agent Claims
+
+Mutating agent writes use target-scoped claim tokens. Read-only inspection stays
+available without a claim, but confirmed writes such as lineage `link-child` and
+claimed content post attach/phase actions require a matching token when a target
+is already claimed.
+
+Create a claim and copy the raw token at creation time:
+
+```bash
+lineage agent claim --project demo-project --scope lineage_workspace --target demo-project:lineage-workspace:<root-asset-id> --target-title "TikTok hook lineage" --agent-name "Codex thread 123" --ttl 20m --json
+export LINEAGE_CLAIM_TOKEN='claim_abc.secret_xyz'
+```
+
+Keep the claim fresh and pass it to mutating commands:
+
+```bash
+lineage agent heartbeat --claim-token "$LINEAGE_CLAIM_TOKEN" --json
+lineage link-child --project demo-project --root <root-asset-id> --child <child-asset-id> --claim-token "$LINEAGE_CLAIM_TOKEN" --confirm-write --json
+lineage agent release --claim-token "$LINEAGE_CLAIM_TOKEN" --json
+```
+
+The app-created claim-aware handoff packet includes the same token export,
+heartbeat, inspect, and write commands. Raw claim tokens are not shown in the
+read-only Agents view.
+
+Use `project_channel` only for rare work that intentionally owns an entire
+project/channel lane. Prefer `lineage_workspace` or `content_post` claims for
+normal target-scoped agent work:
+
+```bash
+lineage agent claim --project demo-project --scope project_channel --target demo-project:channel:tiktok --channel tiktok --agent-name "Channel owner" --ttl 20m --json
+```
+
 ## Codex Plugin
 
 The versioned Codex plugin lives in `plugins/lineage-codex-plugin`. Install the
@@ -118,6 +152,8 @@ Lineage also includes a lightweight Swissifier rich-demo manifest at `fixtures/d
 
 To hydrate the Swissifier demo with real images, use the Demo seed menu's Swissifier `Download media` control. Lineage downloads `swissifier-rich-demo-v1.tar.gz` from the [v0.1.2 GitHub release](https://github.com/mean-weasel/lineage/releases/tag/v0.1.2), verifies the archive checksum, safely unpacks the PNGs into local scratch storage, and then verifies each PNG checksum before loading the rich demo.
 
+Future rich-demo media packs should follow the same split: commit only the lightweight manifest changes, attach the generated media archive to the GitHub release for the app version that first references that archive, then pin the public release URL, archive size, and SHA-256 in the manifest. If a later app release reuses an unchanged media pack, keep the manifest pointed at the original release asset instead of duplicating the archive.
+
 For manual verification or offline restore, the expected archive checksum is:
 
 ```sh