@pulsarinteractive/geniustasker 0.1.0-beta.1 → 0.1.0-beta.10

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

@@ -0,0 +1,62 @@
+# Connect your agent
+
+Choose either direct MCP configuration or the plugin bundle, to avoid registering
+the same server twice. Authenticate once per chosen local context. Permissions
+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.10 auth login --context work
+codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.10 mcp --context work
+```
+
+Restart the host as needed, then inspect its MCP list. Ask the agent to read its
+GeniusTasker identity and list available projects. Configure a different context
+when a separate terminal needs an independent session.
+
+## Claude and other stdio hosts
+
+Merge the `mcpServers.geniustasker` entry from [the example](../examples/mcp.json)
+into the host's documented configuration. Don't replace unrelated servers.
+No token, API key or password belongs in that configuration. Host-specific paths
+and plugin formats vary; use the host's current documentation.
+
+## Install skills separately
+
+Clone this repository into a location you control. For a Codex user-level install,
+copy the `geniustasker` and `geniustasker-memory` folders from `skills/` into
+`~/.agents/skills/`, keeping each `SKILL.md`, references and metadata together.
+For Claude use its supported `.claude/skills/` location. Inspect an existing folder
+before replacing it. Restart the agent and invoke `$geniustasker` or
+`$geniustasker-memory` where the host supports named invocation.
+
+Skills guide workflows; the MCP provides executable tools. The CLI remains useful
+without skills, and skills can use the CLI when an MCP host is not configured.
+
+## Portable plugin bundle
+
+The root `plugin.json` and `mcp.json` follow Agent Plugins 1.0.0. The bundled MCP
+runs locally over stdio and pins a published npm version. Node and npm must be
+available in the execution environment. Authenticate the `work` context first.
+
+The repository also has `.agents/plugins/marketplace.json` for local distribution:
+
+```sh
+codex plugin marketplace add PulsarInteractive/geniustasker-agent-tools
+```
+
+Use the host's Plugins interface to select and enable GeniusTasker. This local
+marketplace is distinct from OpenAI's public directory. Packaging/schema checks
+and SDK transport tests are automated; real host installation is recorded
+separately in the release notes and must not be inferred from those tests.
+
+## Revoke
+
+```sh
+geniustasker auth logout --context work
+```
+
+This revokes the server session before removing its credentials. A failed revoke
+keeps local evidence so it can be retried. Uninstalling a package alone does not
+revoke a remote session.

package/docs/LIMITS.md

@@ -0,0 +1,62 @@
+# 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 |            Starter |                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. The public Starter and Pro plans use `Starter` and `Pro` in API responses.
+
+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.
+
+## MCP and the built-in coach are separate
+
+MCP connects the AI tool you already use to your account. Its external model
+subscription and token charges stay with that tool; agent request credits are
+not model tokens. The built-in GeniusTasker coach has its own account allowance.
+Reaching an agent or coach allowance does not remove your documents or project
+access. Ordinary app traffic remains subject to its separate API limits.
+
+Each server request counts, including discovery, polling and a retry that reaches
+the admission step. A write can consume allowance even if a later domain rule
+refuses it. Replaying the same operation prevents a duplicate edit; it does not
+promise free network requests.
+
+## 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/OPENAI.md

@@ -0,0 +1,21 @@
+# GeniusTasker and OpenAI tools
+
+Use [the hosted ChatGPT connection guide](CHATGPT.md) for a remote OAuth MCP connection. It uses a dedicated GeniusTasker grant and requires no local process or OpenAI API key.
+
+For terminal-based agents, the existing local MCP configuration and skills remain available; see [integrations](INTEGRATIONS.md). Local filesystem features remain local.
+
+Public directory publication is a separate review: [submission checklist](OPENAI_PUBLICATION.md). A custom plugin is not a directory approval or an OpenAI endorsement.
+
+### Reconnecting with edit permissions
+
+The remote catalogue exposes permission-specific read and edit tools. This lets
+ChatGPT request the permissions needed for tasks, planning and other supported
+actions when linking or reconnecting an account. Consent remains editable;
+selecting fewer permissions keeps the connection restricted. Coach tools also
+require the Coach subscription and explicit access to the athlete's program.
+
+Older linked accounts may have only read permissions. Refresh the plugin tools
+and reconnect if editing permissions are missing; verify the connected account
+and capabilities before working. Reconnection never bypasses account quotas.
+The generic read/execute entry points remain for existing clients; new workflows
+should prefer the permission-specific tools after preparing an immutable command.

package/docs/OPENAI_PUBLICATION.md

@@ -0,0 +1,22 @@
+# Official directory publication
+
+A working custom connector is not an approved directory listing. Submission and publication are separate owner-controlled steps.
+
+1. Verify the publishing identity **Pulsar Interactive** in the OpenAI organization and assign the appropriate submission permissions.
+2. Prepare a plugin ZIP with the remote MCP declaration, public metadata and relevant skills. Keep credentials, backend code and private instructions outside it.
+3. Upload a draft, verify the MCP domain using the challenge provided by OpenAI, connect a dedicated demonstration account and resolve the automated findings.
+4. Supply reproducible positive and negative scenarios, a walkthrough recording and release notes. The demo account must contain synthetic data and remain usable for review. Do not provide your personal account.
+5. Submit the draft and required attestations. After approval, choose when to publish. Approval and its timing belong to OpenAI.
+
+Before submission, ensure support, privacy and legal URLs are reachable by reviewers, describe the actual data handled, and match the publisher. Review write/destructive annotations, revocation, least-privilege grants, subscription restrictions and safe retries. Do not advertise availability in the directory before approval and publication.
+
+The private preview websites remain protected. Their current protection must be deliberately reconciled with reviewer access before public submission; it is not removed by installing the connector.
+
+Current official references (checked 23 October 2026):
+
+- [Submit a plugin](https://developers.openai.com/plugins/deploy/submission)
+- [Remote MCP review requirements](https://developers.openai.com/plugins/deploy/app-review)
+- [Plugin guidelines](https://developers.openai.com/plugins/plugin-guidelines)
+- [Authentication](https://developers.openai.com/plugins/build/auth)
+
+This repository does not assert that an OpenAI review has occurred or that the product is endorsed by OpenAI.

package/docs/PLANNING.md

@@ -0,0 +1,79 @@
+# Projects and planning
+
+Use `geniustasker workflow show --topic planning --json` or `tasker_workflow`
+with `topic: planning` for the same guide in CLI, local MCP and ChatGPT.
+Inspect `capabilities` and the current record before preparing a command.
+
+| Operation         | Commands                                                       | Required access                                                                            |
+| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| New project       | `project.create`                                               | `projects:write`, all-resources consent including future projects, available account quota |
+| Project settings  | `project.update`, `project.features`                           | `projects:write`, native project administration                                            |
+| Delete project    | `project.delete`                                               | `projects:write`, project ownership                                                        |
+| Sprint lifecycle  | `sprint.create/update/start/complete/delete`                   | `tasks:write`, native sprint management                                                    |
+| Workflow stages   | `workflow.create/update/delete`                                | `tasks:write`, native project administration                                               |
+| Recurring tasks   | `schedule.create/update/delete`                                | `tasks:write`, native schedule rights                                                      |
+| Project documents | `document.create/update/delete`, `folder.create/update/delete` | `tasks:write`, native content rights                                                       |
+| Memory folders    | `memory.page.create/update/delete` with `directory: true`      | `memory:write`, Memory content rights                                                      |
+
+Existing credentials retain their original permissions. Reconnect and approve
+`projects:write` to use project administration. A grant restricted to selected
+existing projects cannot create another project. A new project created through
+the connector has agent contributions enabled; an existing project's opt-out
+remains controlled by a human administrator. Membership and consent changes
+are not delegated commands.
+
+## Create and configure a project
+
+Generate a UUID v4 once. Use it as `id` and `epoch`, with scope `project:<id>`
+and `expectedRevision: null`. `project.create` accepts a title, optional key,
+type and icon; omitted type/icon default to `Details` and `layers`.
+Keep the returned revision for subsequent edits. Other commands require the
+latest target revision. Never manufacture a revision from a local timestamp.
+
+`project.features` replaces the planning configuration. Read the project first
+and map these fields; preserve values unrelated to the user's request:
+
+| Read field           | Command field     |
+| -------------------- | ----------------- |
+| `backlogEnabled`     | `backlog`         |
+| `sprintsEnabled`     | `sprints`         |
+| `hierarchyEnabled`   | `hierarchy`       |
+| `workflowsEnabled`   | `workflows`       |
+| `votesEnabled`       | `votes`           |
+| `gitHubEnabled`      | `gitHub`          |
+| `useSprintDeadlines` | `sprintDeadlines` |
+| `projectTimeZone`    | `timeZone`        |
+
+The seven switches are required booleans. Use an IANA time zone, such as
+`Europe/Brussels`. Enabling workflows creates the initial stages if none exist.
+Sprints require a Details project. Active sprints prevent disabling sprints.
+
+## Sprint and workflow rules
+
+Sprint creation/editing uses `name`, `goal`, `start` and `end`; dates are ISO
+instants with an offset and end must follow start by at most 180 days. Only one
+sprint can be active. Completing a sprint preserves its history and carries
+unfinished work to `carryToSprint`, or to backlog when that value is null.
+Completed sprints are immutable; deletion is limited to planned sprints.
+
+Workflow creation/editing uses `name`, `category` (`New`, `InProgress`, `Done`)
+and integer `order`. Deleting an occupied stage requires `replacement`, the ID
+of another stage. The final stage of each category cannot be deleted. Task
+status changes caused by stage edits are part of the same server transaction.
+
+## Recurrences and documents
+
+Recurring tasks use `period`, `interval`, `startTime`, `weekDay`, `timeZoneId`
+and optional assignee, deadline, notification and dependency fields. Inspect
+command help for the exact field list. Resolve ambiguous dates/time zones with
+the user. Do not write scheduler state (`disabled`, `nextCheck`, `lastCreation`).
+Deleting a recurrence preserves previously generated tasks.
+
+Project folders use `name` and `parent`; project documents use `title`, `content`
+and `folder`. They are separate from Memory pages. Memory folders use the
+existing page command with `directory: true`, `path` and `parentId`; documents
+keep stable page and block IDs. Folder cycles are rejected by the server.
+
+Prepare then execute one immutable operation. Retain its ID, timestamp and body
+for uncertain retries. Read back affected collections after success. Open apps
+receive the same realtime changes as edits made in the native UI.

package/docs/PROJECT_FILTERS.md

@@ -0,0 +1,77 @@
+# Shared project filters
+
+Keep a reusable task selection for a project’s members. Filters are separate
+from personal list, table or Kanban layout preferences. Creating a filter does
+not change the project’s sprint configuration or install default tags.
+
+Discover `capabilities` before using this guide. The connected service must
+advertise `filters` and `filter.create`, `filter.update`, `filter.delete`.
+Client support alone does not prove those operations are deployed.
+
+## Read before writing
+
+```sh
+geniustasker resources list --scope project:PROJECT_ID --collection filters --json
+geniustasker resources list --scope project:PROJECT_ID --collection tags --json
+```
+
+Use actual IDs from authorized results. Read members, sprints and tasks when
+selecting them. A name is a label, not an identity: renaming a filter preserves
+its ID and the views that reference it. Prefer updating an existing filter over
+creating duplicates.
+
+| Operation                | Delegated permission | Project role                   |
+| ------------------------ | -------------------- | ------------------------------ |
+| Read shared definitions  | `tasks:read`         | Authorized member              |
+| Create, change or delete | `tasks:write`        | Owner or project administrator |
+
+## Criteria
+
+A create draft uses `kind: "filter.create"`, the actual project `scope` and
+`epoch`, a new stable `id`, `expectedRevision: null`, and these data fields:
+
+```json
+{
+  "name": "Upcoming release",
+  "criteria": {
+    "formatVersion": 1,
+    "query": "",
+    "tags": ["ACTUAL_TAG_ID"],
+    "allTags": true,
+    "assignees": [],
+    "statuses": ["New", "InProgress"],
+    "priorities": [],
+    "sprints": [],
+    "epics": [],
+    "placement": null,
+    "blocked": null
+  }
+}
+```
+
+Categories combine with AND. Values within a category combine with OR; `allTags`
+changes tags to AND. Empty arrays leave that category unrestricted. Use
+`unassigned` in assignees for tasks without an owner. Statuses are `New`,
+`InProgress`, `Done`; priorities `Low`, `Normal`, `High`, `Urgent`; placement is
+`Ordinary`, `Backlog`, `Sprint`, or null. `blocked` is true, false or null.
+
+Current bounds: 50 shared filters per project, names of 2–50 characters, query
+up to 256 characters, up to 100 distinct references per category and 8 KiB of
+criteria. Limits and permissions are enforced by the connected service.
+
+Prepare and execute using the normal [immutable command workflow](CLI.md#prepare-execute-and-recover-writes).
+An update requires the latest revision and may change `name`, `criteria`, or
+both. Submit a complete criteria object when changing criteria. A delete uses
+`filter.delete`, the latest revision and empty `data`.
+
+## Changes and unavailable references
+
+Use incremental reads for `filters` just like tasks. A deleted tag does not
+silently remove its condition from an existing filter. New references must be
+live and belong to the same project. Renaming the filter can preserve a removed
+reference until a person deliberately replaces that condition.
+
+If a selected shared filter is missing, deleted, inaccessible or uses an unknown
+format, report it as unavailable. Never treat it as an unrestricted task query.
+Removing a shared filter affects other members’ saved views, so review its uses
+before deletion and follow the user’s authorized scope.

package/docs/RELEASING.md

@@ -0,0 +1,23 @@
+# Release process
+
+1. Update package, lockfile, MCP server version, plugin version and example pins together.
+2. Review public contract/skill changes and run `npm ci`, `npm run verify` and `npm audit`.
+3. Inspect `git diff` and the complete `npm pack --dry-run --json` list. No private repository history or product files may enter this repo.
+4. Pack and inspect the actual archive. `npm publish <archive> --access public --tag beta` requires the maintainer's npm authentication.
+5. Confirm registry version/tag/integrity, install using a fresh cache and exercise real MCP through an explicitly authorized beta account. Keep private results outside this repository.
+6. Tag the corresponding commit and publish accurate release notes. Record host-specific acceptance separately.
+
+CI runs tests and package/privacy checks. It never publishes npm or deploys the
+service. Future trusted publishing should use a reviewed OIDC setup rather than
+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/docs/TESTING.md

@@ -0,0 +1,52 @@
+# Testing
+
+## Run the quality checks
+
+```sh
+npm ci
+npm run verify
+```
+
+`verify` runs formatting, ESLint, tests, package inventory, public-file checks and
+plugin/schema validation. CI runs the same command on Linux and macOS with Node
+22, followed by a dependency vulnerability audit. It has read-only repository
+permissions and no live service credentials.
+
+## Focused checks
+
+```sh
+npm run format:check
+npm run lint
+node --test test/login.test.mjs
+node --test test/process.test.mjs
+npm run check
+npm audit
+```
+
+`npm run format` applies formatting. The generated command catalog and vendored
+schemas are excluded from formatting so their provenance remains stable.
+
+## What the suites cover
+
+| Suite           | Observable guarantees                                                                                           |
+| --------------- | --------------------------------------------------------------------------------------------------------------- |
+| Login           | Consent URL validation, PKCE state/callback handling, denial, cancellation, device-flow deadlines and slow-down |
+| Client/store    | Private file checks, origin binding, serialized renewal and uncertain-token recovery                            |
+| Commands        | Immutable requests, concurrent writes, identity binding, uncertain receipts and conflicts                       |
+| Profiles        | Grant validation, narrowed selection, revision conflicts and rotation uncertainty                               |
+| Changes         | Cursor validation, bounded waits, cancellation and no blind retries after quota or permission failures          |
+| Process         | Real stdio MCP discovery/calls and coordination between separate OS processes                                   |
+| Public boundary | Rejection of excluded files, credentials, symlinks and escaping imports                                         |
+
+Tests create and clean up their own temporary directories and loopback servers.
+They do not require browser sign-in or real project data. Use meaningful scenario
+names, assert behavior at public boundaries and include the failure that motivates
+a regression test. Avoid sleeps as synchronization when an explicit signal works.
+
+## What local tests do not establish
+
+They do not prove admission to the hosted beta, production availability, browser
+provider compatibility on every device or acceptance by each agent host. Release
+verification separately installs the published archive with a fresh cache,
+compares registry integrity and exercises a deliberately authorized test account.
+Record those checks without publishing account data.

package/docs/WORKFLOWS.md

@@ -0,0 +1,37 @@
+# GeniusTasker workflows
+
+| What you want               | Guide topic  | Operations                                                                                                                 |
+| --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Work on a project           | `projects`   | Read project/member configuration; create/edit/archive/restore tasks; create and plan tickets in existing backlogs/sprints |
+| Prepare a shared workflow   | `projects`   | Project tags and saved filters; sprint, recurring schedule and workflow lifecycle                                          |
+| Collaborate                 | `projects`   | Comments, work reports, questions, exact action approvals and member goals                                                 |
+| Organize knowledge          | `memory`     | Independent Memory spaces, folders/documents, role-restricted content and resource references                              |
+| Connect knowledge           | `graph`      | Typed nodes and relations; authorized references across memories                                                           |
+| Recover an interrupted edit | `mutations`  | Preserve the exact request; read back; reconcile a revision conflict                                                       |
+| Connect or fix permissions  | `connection` | Correct account, consent, reconnect and shared quota                                                                       |
+
+Use `tasker_workflow` in MCP or `geniustasker workflow show --topic TOPIC`.
+Discover commands before editing. A readable collection does not imply a matching
+write command. See [projects and planning](PLANNING.md) for lifecycle commands.
+Membership and consent changes remain in the application.
+
+## Example requests
+
+- “Find my tasks in the current sprint and summarize what blocks them.”
+- “Create a project tag named Beta and save a shared filter for those tasks.”
+- “Move these tickets into this existing sprint after checking their revisions.”
+- “Add this decision to the appropriate Memory folder and link its Graph node.”
+- “Refresh this repository’s configured documentation mirror.”
+
+## Local files and linked permissions
+
+Repository mirrors, local image comparison and file upload are CLI/local MCP
+workflows. The hosted ChatGPT connector does not access your local disk or upload
+an arbitrary chat attachment. Reuse stable asset IDs; compare content before
+replacing an image. A Graph link never grants access to its target: when access
+is removed, the node remains but linked private data becomes unavailable.
+
+Existing project agent contributions must be enabled by an authorized member.
+New projects created with projects:write start with contributions enabled. No tool
+can grant itself membership, approve an action as a human, or bypass account
+[limits](LIMITS.md).

package/examples/codex.toml

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

package/examples/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "geniustasker": {
+      "command": "npx",
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.10", "mcp", "--context", "work"]
+    }
+  }
+}