@pulsarinteractive/geniustasker 0.1.0-beta.3 → 0.1.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.0-beta.5 — 2026-10-02
+
+- Incremental repository documentation from selected Memory folders and Graphs,
+  with generated Markdown provenance and optional digest-verified local media.
+- Safe staged exports, local-edit detection, access revalidation, revocation
+  cleanup and account isolation; large Graphs use bounded portable chunks.
+- Tree and Markdown read tools, documentation sync/status and media comparison.
+- Focused documentation, resource and Graph skills with daily/post-work refresh.
+
+Requires the service's `documentationSync` and `protectedMemoryAssets`
+capabilities as appropriate.
+
+## 0.1.0-beta.4 — 2026-10-02
+
+- Short npm overview, focused Memory guide and account usage tables.
+- Explain the UUID v4 identity required for Memory creation before sending an invalid request.
+- Private Memory attachments through resumable MCP/CLI uploads, bounded binary transport and explicit downloads.
+- Memory full-text search, bounded Graph neighborhoods and permission-aware references.
+- Graph node/edge commands and richer document metadata from the API contract.
+- Seven additional MCP tools and matching CLI commands; independent node content survives unavailable references.
+- Shared request size bounds for rich documents, with immutable write retries preserved.
+
+These additions require the corresponding service capabilities.
+
 ## 0.1.0-beta.3 — 2026-09-30
 
 - MIT license for the client, skills and documentation; third-party license notices.

package/README.md

@@ -1,17 +1,13 @@
-# GeniusTasker agent tools
+# GeniusTasker CLI & MCP
 
-Keep project progress, collaborators and your own AI agents in one place.
-This repository contains the public **CLI, local MCP server and agent skills**.
-The GeniusTasker application and service implementation are separate.
-Canonical repository: [PulsarInteractive/geniustasker-agent-tools](https://github.com/PulsarInteractive/geniustasker-agent-tools).
+Manage projects, tasks and knowledge from your terminal or AI assistant.
+Connect once in your browser, choose what your agent can access, and stay in control.
 
-[Install](#install-and-connect) · [Codex and Claude](docs/INTEGRATIONS.md) ·
-[CLI reference](docs/CLI.md) · [OpenAI plugin](docs/OPENAI.md) · [Releases](CHANGELOG.md)
+[Get started](#get-started) · [Agent setup](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/INTEGRATIONS.md) · [Commands](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/CLI.md) · [Usage limits](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/LIMITS.md)
 
-## Install and connect
+## Get started
 
-Requires **Node.js 22.13+** and an account admitted to the development beta.
-Installing the client does not enable access to the service.
+Requires **Node.js 22.13+** and an approved GeniusTasker account.
 
 ```sh
 npm install -g @pulsarinteractive/geniustasker@beta
@@ -19,63 +15,59 @@ geniustasker auth login --context work
 geniustasker projects list --context work --json
 ```
 
-A browser opens: sign in, select projects and independent memories, choose
-permissions, then approve. The terminal finishes automatically. No token to copy.
-For Chrome use `--browser chrome`; remote shells can use `--flow device --no-browser`.
-Production agent access is not open in this beta.
-
-## Connect an agent
-
-After logging in with the `work` context:
-
-```sh
-codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.3 mcp --context work
-```
-
-Other stdio MCP hosts can use [examples/mcp.json](examples/mcp.json).
-The MCP exposes 16 tools for identity, capabilities, projects, memories, bounded
-reads, profiles and journaled changes. It uses the session you explicitly approved.
-GeniusTasker records work; your agent chooses and executes its own workflow.
-
-## Skills
-
-- [GeniusTasker](skills/geniustasker/SKILL.md): project work, tickets and useful handoffs.
-- [GeniusTasker Memory](skills/geniustasker-memory/SKILL.md): independent knowledge,
-  focused reads, stable blocks and resumable imports.
-
-Install the skill folders in your agent's supported skill directory, or use the
-plugin bundle described in [Integrations](docs/INTEGRATIONS.md). npm installation
-alone does not register skills or MCP servers in your agent host.
-
-## Plugin readiness
-
-`plugin.json`, `mcp.json`, `skills/` and the local marketplace catalog form a
-portable **local plugin bundle**. This is not an approved public ChatGPT-directory
-plugin. The hosted HTTPS MCP/OAuth integration remains a separate milestone in
-[OpenAI integration](docs/OPENAI.md).
-
-## Development
-
-```sh
-npm ci
-npm run verify
+Sign in in the browser, select your projects or memories, then approve the requested
+permissions. The terminal connects automatically. No token to copy.
+Installing the package does not grant application access.
+
+## What you can do
+
+| Area                | Features                                                       |
+| ------------------- | -------------------------------------------------------------- |
+| Projects & tasks    | Browse work, update tickets, record progress and read comments |
+| Agent collaboration | Ask for decisions, track replies and keep useful handoffs      |
+| Memory              | Search documents and read the pages you need                   |
+| Graph               | Explore connected ideas and resolve links to Memory content    |
+| Files               | Upload approved attachments and download selected files        |
+| Permissions         | Choose scopes, restrict agent profiles and revoke connections  |
+
+Availability follows your account, the permissions you approve and the service's
+current capabilities. [Memory & Graph guide](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/MEMORY.md).
+
+## Connect your AI assistant
+
+For a stdio MCP host, use this after signing in:
+
+```json
+{
+  "mcpServers": {
+    "geniustasker": {
+      "command": "npx",
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.5", "mcp", "--context", "work"]
+    }
+  }
+}
 ```
 
-Tests use synthetic fixtures and local mock servers. CI has no production credentials.
-`npm run check` checks the public file boundary, package contents and plugin schema.
-See [Contributing](CONTRIBUTING.md), [Architecture](docs/ARCHITECTURE.md),
-[Testing](docs/TESTING.md) and [Release process](docs/RELEASING.md).
+See [Codex, Claude and skills setup](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/INTEGRATIONS.md).
+Your AI assistant uses its own model subscription; this package does not run or
+bill the model. The [OpenAI integration guide](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/OPENAI.md)
+explains the available local integration and hosted integration status.
 
-## Privacy and source boundary
+## Documentation
 
-No application source, backend, account exports, infrastructure credentials or
-private product documents belong here. Only the agent client and its public
-interface contract are included. Credentials stay in the user's private local
-store; never paste them into an issue. See [Security](SECURITY.md).
+| Guide                                                                                                                          | Use it for                                                    |
+| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [CLI reference](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/CLI.md)                           | Commands, browser login, remote terminals and troubleshooting |
+| [Usage limits](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/LIMITS.md)                         | Plan limits, shared account quotas and safe retries           |
+| [Memory & Graph](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/MEMORY.md)                       | Documents, links, attachments and access changes              |
+| [Repository documentation](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/docs/DOCUMENTATION_SYNC.md) | Source selection, Markdown snapshots and freshness            |
+| [Security](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/SECURITY.md)                                | Credential handling and reporting a vulnerability             |
+| [Contributing](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/CONTRIBUTING.md)                        | Local development, tests and contribution guidelines          |
+| [Changelog](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/CHANGELOG.md)                              | Changes in each release                                       |
 
 ## License
 
-The CLI, MCP server, skills and documentation are available under the
-[MIT license](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md) for
-vendor components. The separately hosted GeniusTasker application and backend
-are not part of this repository.
+[MIT](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/LICENSE)
+for this CLI, MCP server, skills and documentation.
+[Third-party notices](https://github.com/PulsarInteractive/geniustasker-agent-tools/blob/main/THIRD_PARTY_NOTICES.md)
+cover included components. The GeniusTasker application and backend are separate.

package/docs/ARCHITECTURE.md

@@ -102,3 +102,43 @@ client operation, CLI/MCP adapter, failure tests and user documentation together
 Prefer existing transport and storage primitives. A future remote MCP adapter is
 a separate integration described in [OpenAI integration](OPENAI.md); the current
 local plugin manifest must not imply that endpoint already exists.
+
+## Focused knowledge reads
+
+`knowledge.mjs` validates bounded search, Graph neighborhood and reference inputs
+for both CLI and MCP. It checks response scope/shape, never follows cursors
+automatically and never persists linked Memory content. `truncated` is an explicit
+partial graph, not evidence that omitted nodes or relations do not exist. Target
+permissions remain server-owned and independent of access to the referring graph.
+
+## Conditional resource cache
+
+`read-cache.mjs` keeps at most 64 responses and 8 MiB in process memory, with
+15-minute idle eviction. Exact query keys include a hashed origin/credential
+realm. Every hit makes an authenticated conditional request; no cache entry can
+bypass current server permissions, quotas or source versions. Servers without
+validators remain compatible and receive ordinary reads.
+
+Concurrent identical reads share one request. Generation fences prevent late
+responses from repopulating a cache after account/profile changes, failures or
+MCP writes. Failed validation clears cached private bodies; there is no stale
+success fallback and no persistent resource cache. Returned values are cloned so
+one tool call cannot mutate another caller's cached result.
+
+## Explicit repository snapshots
+
+`documentation.mjs` validates the bounded tree and Markdown APIs. The sync
+orchestrator keeps the selection independent of projects, compares descendant
+versions, retrieves changed documents, verifies media and rechecks source
+contexts before commit. `documentation-graph.mjs` maintains qualified Graph
+records through incremental cursors and portable chunks of at most 100 records.
+References do not materialize another Memory's private source bodies.
+
+`documentation-store.mjs` owns only the configured destination's `content/`
+subdirectory. A manifest records hashes and provenance. Local edits, unknown
+files, symlinks and account/environment mismatches fail explicitly. A process
+lock, staged tree and rename journal protect concurrent or interrupted exports.
+Network failures leave the previous dated snapshot; current authorization is
+never inferred from a local file. Confirmed scope revocation removes managed
+source content at the next successful check, but cannot retract Git history or
+copies elsewhere. The explicit export is separate from the process read cache.

package/docs/CLI.md

@@ -51,7 +51,7 @@ launching stdio servers with this entry (adjust environment/context as needed):
   "mcpServers": {
     "geniustasker": {
       "command": "npx",
-      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.2", "mcp", "--context", "work"]
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.5", "mcp", "--context", "work"]
     }
   }
 }
@@ -389,7 +389,31 @@ source provenance. Preserve IDs when editing; do not relabel a proposal as a
 verified fact. `pages --id ID` also reads one page. A targeted read has no change
 cursor; obtain one from a complete collection inventory when watching updates.
 Commands `memory.create/update/delete` and `memory.page.create/update/delete`
-require `memory:write`. For a new space, choose one UUID for its root ID, scope
+require `memory:write`. For a new space, choose one UUID v4 for its root ID, scope
 suffix and initial epoch, then use the returned epoch/revision for later writes.
 All edits use the same local command journal and optimistic revision checks as
 project commands. Never copy private source files into this npm package.
+
+## Page access and visual Graph levels
+
+A memory can define `contentRoles` (stable IDs and display names). Membership
+assignments are managed in the application. Page `visibility` is `inherit`,
+`restricted`, or `private`; `readRoles` selects defined roles for a restricted
+page. Restrictions apply through parent folders and to attached files. Content
+roles never grant editing rights. Only memory administrators can change page
+restrictions or move existing pages between parents. Never change sharing as a
+workaround for denied reads.
+
+Resources, search, references and media reads enforce current page access.
+After permission changes, discard cached results and restart incremental reads
+when `reset_required` is returned. An offline copy cannot establish current
+access. Keep Graph nodes and their own notes when a linked page is unavailable.
+
+Nodes accept `imageAssetId` for an image uploaded to the same memory and
+`detailLevel`: `auto`, `overview`, `identity`, or `detail`. The node `kind` is its content type. Overview shows products, projects and brands;
+Identities shows characters, people and entities (never places or scenes). Details
+shows every type and supports type/status filters. Prefer `auto`; an explicit
+`overview` can highlight another type there. Display level is not authorization.
+Upload only approved imagery. Attaching a private image to a shared Graph makes
+it visible to that Graph's readers and requires the user's authorization.
+Read the full current record before editing and preserve its revision.

package/docs/DOCUMENTATION_SYNC.md

@@ -0,0 +1,144 @@
+# Keep product documentation beside your code
+
+Choose the Memory libraries and Graphs relevant to a repository. GeniusTasker is
+the editable source; the CLI produces a dated Markdown snapshot in your chosen
+directory. Memory remains independent of projects.
+
+This workflow requires `documentationSync: true` in `geniustasker capabilities`
+and the `docs sync` command in your installed client. All reads use your current
+account, connection, profile and page permissions.
+
+## Configure a repository
+
+Create a small configuration file, for example `geniustasker-docs.json`:
+
+```json
+{
+  "formatVersion": 1,
+  "sources": [
+    { "scope": "memory:PRODUCT_ID", "pages": true, "graph": true },
+    { "scope": "memory:DESIGN_ID", "parentId": "VISUALS_FOLDER_ID", "pages": true }
+  ],
+  "media": "local"
+}
+```
+
+Use IDs discovered through your own account. Omit `parentId` for a whole library.
+`graph` includes that scope’s Graph, independently of its document subtree.
+`media: "references"` keeps resource IDs without downloading bytes; `local`
+downloads only media used by the selected pages and Graph thumbnails and needs
+`media:read`. Choose up to 50 scopes, with one subtree per scope.
+
+```sh
+geniustasker docs sync --context work --directory docs/geniustasker --file geniustasker-docs.json --json
+geniustasker docs status --directory docs/geniustasker --json
+geniustasker docs sync --context work --directory docs/geniustasker --json
+```
+
+The first call saves the selection. Later calls reuse it; supplying another
+configuration explicitly changes the selection. The recommended destination is
+`docs/geniustasker/`, but choose a path that fits your repository. Exporting private
+knowledge does not publish it or authorize committing it to a public repository.
+
+## What appears locally
+
+All generated files live in the destination’s **`content/`** subdirectory.
+Keep handwritten files alongside `content/`, rather than inside it.
+
+```text
+docs/geniustasker/
+  content/
+    .geniustasker-manifest.json
+    memory-PRODUCT_ID/
+      index.md
+      pages/
+        overview--stable-suffix/index.md
+        visuals--stable-suffix/
+          interface--stable-suffix/index.md
+      resources/RESOURCE_ID.png
+      graph.md
+      graph.json
+      graph/nodes-0000.md
+      graph/nodes-0000.json
+      graph/edges-0000.md
+      graph/edges-0000.json
+```
+
+Pages keep Markdown headings, tables, lists, code and Mermaid blocks. Each starts
+with an automatic-generation notice and ends with source ID, revision, edit time,
+creator/editor and source epoch. Older imported records can have an unknown
+editor; the exporter does not invent one. View diagrams in a Mermaid-capable
+Markdown reader.
+
+Shared resources have one local file per asset ID within the selected Memory.
+The server’s verified SHA-256 is checked when available; unchanged immutable
+assets reuse the previously verified local bytes. Generated files contain no
+bearer tokens or signed download URLs.
+
+Graph JSON is split into chunks of at most 100 records, with a small `graph.json`
+index. The Markdown companions preserve node notes and qualified relations.
+References to another Memory remain source identities: access to a Graph does
+not grant access to linked content, and a missing reference does not erase nodes.
+
+## Efficient updates
+
+The exporter checks current access and folder versions first. It skips unchanged
+branches, retrieves changed Markdown pages individually, and uses Graph change
+cursors after the first inventory. Moves, non-latest-child deletions and restored
+sources are detected. A continuation cannot silently mix source revisions.
+
+An interrupted first export keeps completed downloads in a private cache beside
+the CLI credentials, outside the repository. The next attempt checks access and
+the current tree again before reusing a page with the same revision. Graph and
+media downloads also resume when their source checkpoint still matches. A quota
+reset therefore does not require downloading the same first pages repeatedly.
+Changed or inaccessible entries are discarded. The temporary cache is bounded
+to twice the selected byte budget and is removed after a successful sync.
+
+Use `memory tree --scope memory:ID` to inspect a bounded folder. Continue with
+`--after`, `--epoch` and `--checkpoint`. Use `memory markdown --scope memory:ID
+--page PAGE_ID` for one page, optionally with its expected `--revision`.
+
+There is no background polling. For a repository using generated knowledge:
+
+1. At the beginning of a working day, check `docs status`; sync before relying on
+   a snapshot whose freshness has not been checked that day.
+2. Read local files for the task. Fetch only missing source details through MCP.
+3. Apply relevant documentation changes to GeniusTasker using MCP, preserving
+   IDs, hierarchy, source authority and expected revisions.
+4. Sync again after finishing work that changes the documented product or Graph.
+
+An offline or refused check never advances the successful check time. Local
+files remain dated snapshots, not evidence of present authorization.
+
+## Failure and recovery
+
+| Situation                               | Result and next step                                                                                                                     |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Network error or interrupted download   | The previous complete snapshot remains. Rerun sync; completed downloads resume after fresh authorization and version checks.             |
+| Source changed during export            | No mixed snapshot is installed. Reread and rerun.                                                                                        |
+| Confirmed scope denial                  | Its managed snapshot is removed and marked unavailable. Regrant permits a fresh export. This cannot retract Git history or other copies. |
+| Local edits/additions inside `content/` | Sync stops without overwriting them. Apply edits through MCP and preserve handwritten files outside the managed directory.               |
+| Account/environment changed             | Use a separate destination; the exporter refuses to merge identities.                                                                    |
+| Another exporter is running             | Wait for it. A crashed process can be released with `docs unlock --directory ...`; a living or foreign-host process is never unlocked.   |
+| Interrupted directory replacement       | The next sync restores the previous snapshot when necessary, then revalidates. It does not publish unchecked staged data.                |
+| Quota or rate limit                     | Follow the returned reset/retry guidance. Do not create profiles to bypass account limits.                                               |
+
+Symlink destinations, path traversal and conflicting generated paths are refused.
+The default budget is 20,000 files and 256 MiB. Explicit `--max-files` (up to
+100,000) and `--max-bytes` (up to 4 GiB) can raise it for a reviewed selection;
+individual files remain bounded. These local budgets do not increase server
+quotas. Narrow the selection if exporting everything is unnecessary.
+
+## Agent tools
+
+| Tool                     | Purpose                                                         |
+| ------------------------ | --------------------------------------------------------------- |
+| `tasker_memory_tree`     | Inspect a folder and descendant versions without loading bodies |
+| `tasker_memory_markdown` | Fetch one source page with provenance                           |
+| `tasker_docs_status`     | Inspect the saved date and selections locally                   |
+| `tasker_docs_sync`       | Refresh the explicit selection in a local directory             |
+| `tasker_media_compare`   | Compare a local file with an existing resource before upload    |
+
+The documentation, media and Graph skills describe the corresponding workflows.
+They do not authorize account changes or publication outside the user’s task.

package/docs/INTEGRATIONS.md

@@ -7,8 +7,8 @@ are selected in the browser and enforced by the service on every request.
 ## Codex: direct MCP
 
 ```sh
-npx -y @pulsarinteractive/geniustasker@0.1.0-beta.3 auth login --context work
-codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.3 mcp --context work
+npx -y @pulsarinteractive/geniustasker@0.1.0-beta.5 auth login --context work
+codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.5 mcp --context work
 ```
 
 Restart the host as needed, then inspect its MCP list. Ask the agent to read its

package/docs/LIMITS.md

@@ -0,0 +1,49 @@
+# Usage limits
+
+CLI and MCP share your GeniusTasker account limits. Creating more agent profiles,
+opening more terminals or changing devices does not give additional allowance.
+The service reports current limits through `geniustasker capabilities --json`.
+
+## Agent requests
+
+| Allowance                     |  Free |            Premium |                Pro |
+| ----------------------------- | ----: | -----------------: | -----------------: |
+| Requests per 60 seconds       |    30 |                120 |                300 |
+| Write requests per 60 seconds |     5 |                 20 |                 60 |
+| Monthly request credits       | 5,000 | No monthly ceiling | No monthly ceiling |
+| Monthly write requests        |   500 | No monthly ceiling | No monthly ceiling |
+
+Write requests also count toward the request limit. For Free accounts, a read
+costs one monthly credit and a write costs five; both monthly limits must have
+capacity. Monthly counters reset at the beginning of the next calendar month
+in UTC. Premium appears as `Starter` in API responses; Pro appears as `Pro`.
+
+These are the current service settings, not a pricing commitment. Short-window
+limits provide traffic protection and can apply approximately by location;
+clients must follow the service response. Resource limits for projects, members,
+Memory, storage and attachments are separate and still apply. Availability also
+requires account approval and an explicitly granted agent connection.
+
+## When a limit is reached
+
+| Response                         | Next step                                                             |
+| -------------------------------- | --------------------------------------------------------------------- |
+| Temporary rate limit (`429`)     | Wait for the reported retry time; do not loop or open another context |
+| Free monthly allowance exhausted | Wait for the reported reset or change plan when available             |
+| Resource capacity reached        | Free capacity or change plan before creating more data                |
+| Permission refused (`403`)       | Ask the account or resource owner to review access                    |
+| Interrupted write                | Keep its operation ID and retry that same operation                   |
+
+The client preserves a write's immutable journal for safe retries. A timeout is
+not proof that the write failed. Read the latest record after a revision conflict
+before preparing a new operation.
+
+## Keep reads focused
+
+- List one page of spaces or resources at a time and follow its cursor as needed.
+- Use Memory search and its page index before downloading document bodies.
+- Explore a bounded Graph neighborhood instead of loading every node.
+- Reuse checkpoints for change reads; honor `restart_read` when the service asks.
+- Local cache hits revalidate access. Revoked permissions never become an offline grant.
+
+See [CLI reference](CLI.md) for commands and [Memory & Graph](MEMORY.md) for examples.

package/docs/MEMORY.md

@@ -0,0 +1,38 @@
+# Memory and Graph
+
+Memory stores structured documents independently of projects. Graph connects
+nodes and links them to a page or a stable document block. These commands require
+the matching deployed service capabilities; check `geniustasker capabilities --json` before using them.
+
+```sh
+geniustasker memory search --scope memory:ID --query "release checklist" --json
+geniustasker graph explore --scope memory:ID --center NODE_ID --depth 2 --json
+geniustasker memory resolve --scope memory:ID --page PAGE_ID --block BLOCK_ID --json
+```
+
+The matching MCP tools are `tasker_search`, `tasker_graph` and `tasker_reference`.
+Search is paginated; Graph returns a bounded neighborhood and reports truncation.
+Use `resources list` for complete selected records and `commands describe` for
+contract-derived node/edge write fields. Writes keep the same immutable journal.
+
+References recheck current access. If a friend withdraws access, the content
+becomes unavailable while the node and its own text remain intact. A new grant
+restores resolution; a link never grants access by itself. The client does not
+cache resolved content. Discover capabilities before selecting a workflow.
+
+## Attachments
+
+Discover `mediaUploadAvailable` and `maxUploadBytes` first. Prepare one explicitly
+selected file with `media prepare --scope memory:ID --epoch EPOCH --file diagram.png
+--content-type image/png`, then `media upload --operation UUID`. Keep that operation
+ID after a timeout: retries verify the same bytes and do not create a second file.
+Use the returned `assetId` in an image or attachment block. Images, PDF and plain
+text are supported up to 15 MB; storage is charged to the Memory owner.
+
+MCP equivalents are `tasker_media_prepare`, `tasker_media_upload`,
+`tasker_media_action` and `tasker_media_download`. Downloads require an explicit
+new local path and fresh read access. Removal leaves document blocks in place
+so people can see and repair the unavailable attachment. No credentials, URLs
+with public access tokens or file bytes are embedded in documents.
+
+See the [CLI reference](CLI.md) for document blocks, page roles, node types, images and detailed command examples.

package/docs/RELEASING.md

@@ -14,3 +14,10 @@ committing an npm token; it is not configured by this repository.
 Published npm versions are immutable. Use a new version for package changes.
 
 Canonical repository: https://github.com/PulsarInteractive/geniustasker-agent-tools
+
+The npm package page and unqualified installs use the `latest` tag. After verifying
+the release archive, explicitly update both the intended channel and the default
+version; do not leave `latest` pointing at a superseded license or README. Verify
+`npm view @pulsarinteractive/geniustasker dist-tags license repository.url --json`
+and inspect the actual npm page. An old published archive is immutable; tags do
+not rewrite its contents.

package/examples/codex.toml

@@ -1,3 +1,3 @@
 [mcp_servers.geniustasker]
 command = "npx"
-args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.3", "mcp", "--context", "work"]
+args = ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.5", "mcp", "--context", "work"]

package/examples/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "geniustasker": {
       "command": "npx",
-      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.3", "mcp", "--context", "work"]
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.5", "mcp", "--context", "work"]
     }
   }
 }

package/mcp.json

@@ -4,7 +4,7 @@
     "geniustasker": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.3", "mcp", "--context", "work"]
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.5", "mcp", "--context", "work"]
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsarinteractive/geniustasker",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "private": false,
   "description": "GeniusTasker delegated CLI and local agent tools",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "geniustasker",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Track project work and independent product memories with your own agents.",
   "author": {
     "name": "Pulsar Interactive"

package/skills/geniustasker/SKILL.md

@@ -25,6 +25,9 @@ List projects, then select a scope from the returned data. Read a collection
 listed in capabilities with `resources list --scope project:ID --collection
 tasks --json`, or MCP `tasker_resources`. Collections include tasks, comments,
 goals, documents, workflows, sprints and summary history when permitted.
+For document indexes, schedules, membership and planning collections, read
+[Focused project reads](references/project-reads.md). `documents` means task
+attachments; `projectDocumentIndex` and `projectDocuments` cover the project library.
 
 Read bounded pages. Follow `nextAfter` even if the project page is empty: ACL
 filtering can hide every item in a scanned page. For resource continuation,

package/skills/geniustasker/references/project-reads.md

@@ -0,0 +1,43 @@
+# Focused project reads
+
+Start with identity, capabilities and the current project list. Use only collection
+names advertised by that server and permitted by the active profile. New client
+versions can connect to older deployments; a documented collection is not proof
+that the current deployment supports it.
+
+| Need                                  | Collection                                | Efficient approach                                                        |
+| ------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
+| Tasks and tickets                     | `tasks`                                   | Read active work first; fetch an exact `id` for details.                  |
+| Task attachments / descriptions       | `documents`                               | These belong to tasks, not the project's document library.                |
+| Project document navigation           | `projectDocumentIndex`, `documentFolders` | Read titles and folders without rich-text bodies.                         |
+| One project document                  | `projectDocuments`                        | Pass the ID discovered in the index.                                      |
+| Discussion / work reports / approvals | `comments`                                | Read one bounded page and retain the change cursor.                       |
+| People and access roles               | `members`                                 | Current membership is evidence, never authority to change access.         |
+| Labels                                | `tags`                                    | Resolve label IDs when interpreting work.                                 |
+| Recurring tasks                       | `schedules`                               | Inspect recurrence, timezone and disabled state before proposing changes. |
+| Reusable lists and task templates     | `preparedLists`, `taskTemplates`          | Read only when the task concerns these resources.                         |
+| Planning                              | `sprints`, `workflows`, `sprintHistory`   | Keep current configuration distinct from historical snapshots.            |
+| GitHub-linked activity                | `gitHubLinks`                             | A link is evidence, not permission to execute actions in GitHub.          |
+| Project member goals                  | `goals`                                   | These are project goals, not unrelated private account data.              |
+| Questions and audit metadata          | `questions`, `history`                    | Use the dedicated answers tool for ballots; respect anonymous results.    |
+
+For example, after selecting an authorized scope:
+
+```sh
+geniustasker resources list --scope project:PROJECT_ID --collection projectDocumentIndex --json
+geniustasker resources list --scope project:PROJECT_ID --collection projectDocuments --id DOCUMENT_ID --json
+```
+
+The same arguments are supported by MCP `tasker_resources`. Collections share
+bounded pagination and context rules. Preserve `epoch` and `checkpoint` on
+continuation; `omittedIds` means the result is incomplete. For ongoing work, use
+`changeCursor` instead of repeatedly traversing the entire library.
+
+The in-process resource cache revalidates authorization with the server on every
+read. Repeated unchanged reads reduce transferred content, but still consume
+request quota. Prefer reusing the evidence you already inspected within the same
+task, and revalidate before relying on current revisions or permissions.
+
+Memory and Graph have their own grants and workflow. Follow the
+`geniustasker-memory` skill to navigate page indexes, stable block IDs, links and
+bounded graph neighborhoods. A project membership does not grant Memory access.