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

package/docs/CLI.md

@@ -0,0 +1,395 @@
+# GeniusTasker CLI and MCP reference
+
+Connect your own AI tools to your projects: read progress, work on tickets,
+comment, ask questions and keep a useful handoff. Your account and project
+permissions remain the limit. GeniusTasker does not run your agent or bill its
+external model tokens.
+
+## Install and connect
+
+Requires Node.js 22.13 or newer. Install the beta:
+
+```sh
+npm install -g @pulsarinteractive/geniustasker@beta
+geniustasker auth login
+geniustasker whoami --json
+geniustasker projects list --json
+```
+
+Login opens your browser. Sign in to GeniusTasker, choose projects, independent memories and
+permissions, then approve the connection. The CLI receives a one-use code with
+PKCE; it never asks for your password. The consent page does not load the app tutorial. Decline there or use Ctrl-C to stop.
+If the browser cannot open, use the link printed in your terminal.
+
+**This beta defaults to the development environment.** Your account must be
+admitted to the beta; installing the package does not grant access. Production
+agent access is closed. Use `--environment production` only when that rollout is
+announced. No subscription purchase is performed by the CLI.
+
+For a remote machine, use `geniustasker auth login --flow device --no-browser`.
+For Chrome specifically, use `--browser chrome`. `--context work` creates a
+separate local session for an independent terminal; it does not grant extra quota.
+The browser offers the supported permissions, with read-only access selected by
+default. Write permissions require an explicit choice. To narrow the permissions
+offered by the browser, pass `--scope`, for example:
+
+```sh
+geniustasker auth login --context work --scope 'projects:read tasks:read tasks:write comments:write goals:read goals:write'
+```
+
+The browser still requires the human to explicitly grant each permission.
+Revoke a session using `geniustasker auth logout --context work` or Account →
+Agent connections in the app. Do not put tokens in commands or MCP configuration.
+
+## Local MCP
+
+Authenticate with `geniustasker auth login --context work` outside the MCP process first. Configure a client capable of
+launching stdio servers with this entry (adjust environment/context as needed):
+
+```json
+{
+  "mcpServers": {
+    "geniustasker": {
+      "command": "npx",
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.2", "mcp", "--context", "work"]
+    }
+  }
+}
+```
+
+No token belongs in that configuration. The server uses the official MCP SDK
+and offers `tasker_identity`, `tasker_capabilities`, `tasker_projects` and
+`tasker_memories`, `tasker_resources`, plus `tasker_prepare_command`, `tasker_execute_command`,
+`tasker_retry_command` and `tasker_inspect_operation`. Profile tools are
+`tasker_profiles`, `tasker_create_profile`, `tasker_restrict_profile` and
+`tasker_select_profile`. `tasker_question_answers` reads human responses.
+`tasker_changes` and `tasker_watch` support resumable changes and bounded waits.
+Only MCP JSON-RPC is written to stdout. This is a local
+stdio integration, not a hosted MCP service or a marketplace-approved plugin.
+The bundled `skills/geniustasker/` folder can be copied into the skill directory
+supported by your chosen agent. Specific clients may use a different config
+format; their integration guides and release validation remain separate work.
+
+## Paging and failures
+
+Commands read one bounded page. Continue with `--after` when `nextAfter` is
+non-null, even for an empty filtered project page. Resource continuation also
+requires `--epoch` and `--checkpoint` from the first page. A context change
+requires restarting the read. `omittedIds` means oversized legacy records were
+excluded. Tasks support `--archive active|archived|all`.
+
+`--json` gives one versioned result on stdout. Login displays readable progress
+by default; with `--json`, its progress uses versioned envelopes on stderr.
+Error envelopes also use stderr and do not contain credentials. Exit codes: 2 usage, 3 authentication,
+4 permission, 5 conflict, 6 rate limit, 7 temporary failure, 1 other failure.
+Honor `retryAfterSeconds`; there is no hidden retry loop or subscription upgrade.
+
+### Incremental reads and bounded waits
+
+Complete a resource inventory first. Its final page supplies `changeCursor`;
+intermediate pages supply null. Keep this cursor with the same account, scope,
+collection and archive view. For example, with the actual returned cursor:
+
+```sh
+geniustasker changes list --environment development --context work --scope project:ID --collection tasks --cursor CURSOR --json
+geniustasker changes watch --environment development --context work --scope project:ID --collection tasks --cursor CURSOR --wait-seconds 30 --json
+```
+
+Apply all items and removal markers before retaining `nextCursor`. Follow
+`hasMore` even if items is empty. These are current projections of changed IDs,
+not a historical snapshot; duplicate IDs are possible and record revisions can
+be newer than the page checkpoint. Apply newer/equal revisions idempotently and
+never replace a newer cached row with an older one. Omissions remain incomplete
+evidence. On `restart_read`, replace the collection from a fresh inventory.
+Retained-history deletion also demands a full read to protect private audit IDs.
+
+Watch returns `reason: changes|timeout`, a page (possibly null on timeout), the
+number of completed polls and a continuation. It waits at most 60 seconds,
+polling no faster than five seconds. Every poll uses the account's normal quota
+and live permissions. Ctrl-C or MCP cancellation interrupts it; errors stop it
+without blind retries. There is no daemon or automatic background agent. A
+Free monthly budget refusal preserves `retryable: false` and its `resetAt` time.
+
+## Account rate limits
+
+Identity and capabilities expose the current server `rateLimits`. All CLI/MCP
+contexts and agent profiles on the same account share them. Free allows 30
+requests per 60 seconds, Starter 120, Pro 300; within those totals, write requests
+are limited to 5, 20 and 60 respectively. These native Cloudflare limits are
+approximate and location-local, not billing meters. A command can change several
+entities; the rate unit is a request, not an entity or a physical SQL write.
+
+Starter/Pro have no monthly agent credit/write-request cutoff. Free has 5,000
+monthly credits (read request 1, write request 5) and 500 write requests, resetting
+at the next UTC month. Every poll/replay consumes the applicable request limits.
+On a temporary 429, honor `retryAfterSeconds` (currently a conservative 60 seconds)
+before resuming. The CLI reports the error without automatically retrying writes;
+keep the same journaled operation ID, issuedAt and content. Do not switch tokens,
+profiles or contexts to evade the account limit. A write-only throttle leaves
+reads available within their request/Free-credit budget.
+
+## Credential storage and recovery
+
+Credentials live in `~/.geniustasker/<context>.json`, outside repositories.
+On POSIX systems the directory is 0700 and files are 0600, with file ownership,
+symlink and hard-link checks. This protects against other OS users; it is not a
+keychain and does not isolate processes running as you. Windows ACL and native
+keychain integration have not been validated in this preview.
+
+Refresh is serialized across processes and writes are atomic. An uncertainty
+marker is saved before rotation: after a lost response, run logout then login
+instead of replaying a one-use refresh token. Logout revokes the session family
+on the server before removing credentials; on failure it keeps them for retry.
+The account's Agents page can revoke a session or whole connection at any time.
+
+A killed process can leave an empty `<context>.json.lock` directory. Stop every
+CLI/MCP process using that context before removing only that empty lock
+directory. Never remove a live client's lock. Then run logout/login if renewal
+was interrupted. `doctor` exposes no credential values.
+
+For an isolated local backend, `--origin http://127.0.0.1:PORT --allow-local`
+explicitly enables loopback HTTP. Hosted credentials are origin-bound and cannot
+be sent there. Redirects on credential-bearing API requests are refused.
+
+Protocol references: [OAuth device authorization](https://www.rfc-editor.org/rfc/rfc8628),
+[OAuth token revocation](https://www.rfc-editor.org/rfc/rfc7009),
+[OAuth metadata](https://www.rfc-editor.org/rfc/rfc8414), and the
+[official MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).
+
+## Prepare, execute and recover writes
+
+Request the relevant permissions when connecting, for example:
+
+```sh
+geniustasker auth login --context work --environment development --scope 'projects:read tasks:read tasks:write comments:write goals:read goals:write' --browser chrome
+```
+
+The person chooses the effective grant. A project administrator must also enable
+agent contributions. Discover capabilities and read the project instructions.
+`commands describe --json` describes fields and the draft/request JSON schemas
+from the product contract. It does not grant access or prove server activation.
+
+Save a draft in a private JSON file (replace IDs/epoch with current reads):
+
+```json
+{
+  "scope": "project:PROJECT_ID",
+  "epoch": "EPOCH_FROM_READ",
+  "id": "NEW_RECORD_UUID",
+  "expectedRevision": null,
+  "kind": "task.create",
+  "data": { "title": "Prepare the next release" }
+}
+```
+
+Then use the same context/environment for the whole workflow:
+
+```sh
+geniustasker commands prepare --file draft.json --context work --environment development --json
+geniustasker commands retry --operation OPERATION_ID --context work --environment development --json
+geniustasker commands inspect --operation OPERATION_ID --context work --environment development --json
+```
+
+Prepare saves a stable UUID/timestamp and sends nothing. Retry executes that
+saved operation, whether still prepared or uncertain. Alternatively,
+`commands execute --file request.json` accepts a complete request containing
+`operationId` and `issuedAt` and journals it before sending. Never regenerate
+those values to recover a timeout. Execution errors retain the operation ID.
+
+The journal lives in `~/.geniustasker/operations/<context>/` with private file
+permissions. It contains project text and receipts, never credentials. It is
+bound to the original connection, profile, session and API environment. A new
+login cannot silently replay an old session's operation. Inspection is local
+evidence, not a live permission check. A confirmed retry is labeled
+`local_receipt`; a newly obtained receipt is labeled `server`.
+
+After a revision conflict, reread the affected records and prepare a new edit.
+A pending or lost result requires an identical retry. No write is automatically
+retried. Journal locks serialize different processes. If a process is killed,
+stop all clients before removing that operation's empty `.json.lock` directory.
+Keep its JSON request and retry it; do not erase uncertain operations. Journal
+retention/cleanup automation remains pending. Logout removes credentials but
+retains these records so the outcome can still be inspected.
+
+Commands cover tasks, dependencies, archive/restore, ticket creation/planning,
+comments and goals. `ticket.plan` uses the project ID/root revision and per-task
+numeric `expectedVersion`; `ticket.create` requires a UUID record ID. Comments
+use a text string and mentions array. An agent can edit/delete only comments
+authored by its profile. Server receipts expose changed IDs/revisions, not
+record bodies; read them separately if your grant permits it.
+
+Local validation includes separate processes sharing one write, immutable retry
+after lost responses, strict inputs, receipt validation and an official MCP
+client communicating through stdio to actual Worker/SQLite domain services.
+Compatibility with each agent host requires its own connection test.
+
+## Agent profiles and terminal identity
+
+The initial profile works without configuration. Use independent named contexts
+for independent terminals or accounts; a context shared by two processes is one
+session, so selecting its profile affects both. Profile names are for attribution,
+not extra memberships, API budgets or permission grants.
+
+```sh
+geniustasker profiles list --context work --environment development --json
+geniustasker profiles create --file profile.json --context work --environment development --json
+geniustasker profiles select --profile PROFILE_ID --context work --environment development --json
+geniustasker whoami --context work --environment development --json
+```
+
+`profile.json` contains `id` (one UUID chosen once and retained), `name`, and
+`grant` with `allResources`, `resourceIds`, `permissions`, following `whoami`'s
+grant shape. Use actual project scopes from the API. Creation never switches the
+terminal automatically. The new grant must fit both the current profile and the
+connection. After a lost creation reply, list profiles and reconcile that UUID;
+retrying it cannot allocate a second profile. Do not replace its UUID blindly.
+
+`profiles restrict --file restriction.json` changes only the current profile.
+The file must include its `profileId`, current `expectedRevision`, `name`, and
+narrower/equal `grant`. It cannot undo a previous restriction or edit another
+profile. After a lost reply, read `whoami` to see the saved revision and grant
+before preparing another edit. The explicit profile ID prevents a saved draft
+from editing another profile when a process changed the shared context.
+
+Selection lists only eligible profiles in the same connection, then checks the
+source and destination revisions while atomically rotating both credentials.
+It never extends the session's absolute lifetime. The previous access token stops
+working, so a request in flight cannot silently become the selected profile.
+A restricted profile cannot switch back to the broader Default profile. Broader
+rights need a human decision in the app or a fresh human-approved connection.
+Saved task-operation journals stay bound to their original profile and cannot be
+adopted by a different one. Reconcile pending work before selecting another.
+
+A definite `profile_selection_conflict` or `profile_selection_denied` preserves
+the previous usable credentials; read the profile list again. An unknown rotation
+outcome requires logout/login, just like an unknown refresh. Credentials never
+appear in selection results, CLI output, MCP tool results or package artifacts.
+
+## Ask a human on a ticket
+
+Request `questions:write` explicitly when connecting; an existing comments grant
+alone cannot publish a question. Questions reuse the project's vote feature and
+its human access rules. Agent contributions and project votes must both be enabled.
+The contract offers fourteen write commands and thirteen MCP tools in this preview.
+
+Prepare `question.create` with a new retained question UUID, current scope epoch,
+null expected revision and this `data` shape (replace IDs and deadline):
+
+```json
+{
+  "task": "TICKET_ID",
+  "question": "Which checks should I run before the release review?",
+  "description": "I have finished the implementation and need your acceptance criteria.",
+  "answerKind": "Text",
+  "eligibleUsers": ["HUMAN_USER_ID"],
+  "closesAt": "2026-10-05T16:00:00Z"
+}
+```
+
+An explicit audience and future deadline are required for agent questions. `Text`
+accepts named answers of up to 2,000 UTF-16 code units and at most 50 recipients.
+`YesNo` provides the two canonical options. `Choices` requires 2–12 distinct
+options, with `selection: "Single"` or `"Multiple"`; choices can be anonymous.
+An agent cannot submit a human ballot. A reply does not expand API permissions
+or grant authority for unrelated external actions.
+
+Use the usual prepare/retry journal for creating and closing questions. Read
+`resources list --scope project:ID --collection questions --json` to find their
+current revisions, then:
+
+```sh
+geniustasker questions answers --scope project:ID --question QUESTION_ID --context work --environment development --json
+```
+
+MCP provides `tasker_question_answers`. Follow `nextAfter` with the original
+`epoch` and `checkpoint`; restart after a changed snapshot. Named answers are
+paged ten at a time. Anonymous questions expose no respondents or running totals;
+after closing they expose only totals. A changing private ballot does not alter
+an open anonymous question's public checkpoint.
+
+`question.close` takes the question's current revision and empty `data`. A
+profile can close only questions it created. It cannot answer on behalf of its
+owner, impersonate another profile, or use a poll result as new authorization.
+
+## Work updates and handoffs
+
+Prepare `task.report` through the normal command journal with the current task
+revision and `tasks:write`. `phase` is `Working`, `NeedsInformation` or
+`NeedsReview`; `summary` is required, `nextSteps` is required for both waiting
+phases, and `evidence` is an array of up to eight `{label, url}` HTTPS links.
+`mentions` is optional. The ticket must be open, unarchived and agent-enabled.
+
+The result is one task transition and one attributed, immutable discussion
+receipt. Read `workPhase`/`lastWorkReport` on the task and `workReport` on its
+comment. Completing/reopening a ticket clears its current phase. A report is
+progress information, not approval or proof independently verified by Tasker.
+Correct published reports with a new report; never rewrite an older receipt.
+
+## Ask for approval of one precise action
+
+Connect with `approvals:write` explicitly, alongside the read grants needed to
+review the task and its discussion. Discover the commands through capabilities.
+Prepare `approval.request` with a retained request UUID, expectedRevision null and:
+
+```json
+{
+  "task": "TASK_ID",
+  "taskRevision": "CURRENT_TASK_REVISION",
+  "title": "Publish the reviewed preview",
+  "summary": "Publish build one to the private preview environment.",
+  "actionJson": "{\"build\":\"one\",\"environment\":\"preview\"}",
+  "approver": "HUMAN_MEMBER_ID",
+  "expiresAt": "A_FUTURE_ISO_TIMESTAMP"
+}
+```
+
+The deadline is one minute to seven days ahead. The approver must be a current
+human member with ticket editing rights; the requesting account needs those
+rights too. Read `comments` for the request's `approval` object and revision.
+The designated human reviews the request in the app. No CLI or MCP command can
+approve on their behalf. A question answer, comment or work report is not an
+approval. Do not store credentials in the action JSON or summary.
+
+When Approved, prepare `approval.consume` on that comment with its current
+expectedRevision and data `{ "requestVersion": "ORIGINAL_REQUEST_REVISION",
+"actionJson": "THE_EXACT_REVIEWED_ACTION_JSON" }`. Only its original profile can
+consume; the task and access must still match. Reuse prepare/retry/inspect for
+network uncertainty. A terminal request cannot authorize a second operation.
+`approval.cancel` uses current expectedRevision and `{ "requestVersion": "..." }`
+when the request is no longer needed, including stale or expired requests.
+
+Tasker records authorization and never runs the external action. Use the request
+ID as an idempotency key where the external system supports it. After a crash or
+an uncertain external result, inspect that system before acting again. Replaying
+a successful consumption receipt does not authorize repeating its side effect.
+
+## Package boundary
+
+Only the CLI/MCP source, its generated public command catalog, bundled agent skill
+and the selected guide/plugin files are distributed. Application source, infrastructure configuration,
+private product documents, test identities and credentials are excluded. No
+installation script runs and no background daemon or telemetry is installed.
+The standalone client and skills are distributed under the MIT license.
+Third-party components retain their original licenses.
+
+## Independent memories
+
+A memory is an account resource (`memory:ID`), not a project attachment. The agent
+chooses which project and memory to use independently, within the user's grants.
+Use a small index first, then fetch only the page you need:
+
+```sh
+geniustasker memories list --json
+geniustasker resources list --scope memory:ID --collection pageIndex --json
+geniustasker resources list --scope memory:ID --collection pages --path brand/identity --json
+```
+
+Memory pages contain Markdown blocks with stable IDs, a path, tags and optional
+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
+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.

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.3 auth login --context work
+codex mcp add geniustasker -- npx -y @pulsarinteractive/geniustasker@0.1.0-beta.3 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/OPENAI.md

@@ -0,0 +1,37 @@
+# OpenAI integration
+
+## Available in this repository
+
+The CLI authenticates through browser consent and exposes a local stdio MCP.
+Two skills and portable plugin/MCP manifests are packaged together. Direct
+Codex MCP configuration is documented in [Integrations](INTEGRATIONS.md).
+Nothing here is an OpenAI directory approval or a hosted remote MCP endpoint.
+
+## Hosted plugin milestone
+
+| Work                              | Acceptance                                                                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTPS Streamable HTTP MCP adapter | Real initialize, tools/list and tool calls; reuse existing product commands and quotas                                                                   |
+| MCP OAuth compatibility           | Protected-resource and authorization discovery, audience/resource binding, supported client registration, allowed callbacks, PKCE, expiry and revocation |
+| Host authentication               | Real browser consent, resource-limited reads, denied access and reauthentication                                                                         |
+| Writes                            | Explicit grants, correctly annotated tools, immutable retries and conflicts; no blanket approval                                                         |
+| Optional company-knowledge search | Authorized search/fetch with user-openable citations and bounded results                                                                                 |
+| Plugin review                     | Accurate install copy, privacy/terms links, domain verification, real test account, honest limitations                                                   |
+
+The current CLI OAuth flow is a foundation; it is not proof that every hosted
+MCP client's registration and resource-discovery requirements are implemented.
+A hosted manifest requires a deployed and tested MCP server and a registered
+application identifier. Embedded UI is optional.
+
+The remotely hosted backend can remain private. A public source repository is a
+client distribution and review surface, not an access grant to user data.
+
+## Official references
+
+Checked 30 September 2026:
+
+- [MCP in Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)
+- [Plugin packaging](https://developers.openai.com/plugins/build/plugins)
+- [MCP hosting](https://developers.openai.com/plugins/build/mcp-server)
+- [Authentication](https://developers.openai.com/plugins/build/auth)
+- [Connect and test](https://developers.openai.com/plugins/deploy/connect-chatgpt)

package/docs/RELEASING.md

@@ -0,0 +1,16 @@
+# 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

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/examples/codex.toml

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

package/examples/mcp.json

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

package/mcp.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "geniustasker": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@pulsarinteractive/geniustasker@0.1.0-beta.3", "mcp", "--context", "work"]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsarinteractive/geniustasker",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "private": false,
   "description": "GeniusTasker delegated CLI and local agent tools",
   "type": "module",
@@ -14,12 +14,27 @@
     "bin/",
     "src/",
     "skills/",
-    "README.md"
+    "docs/",
+    "examples/",
+    "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "plugin.json",
+    "mcp.json",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSES/"
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node tools/check-package.mjs",
-    "prepublishOnly": "npm test && npm run check"
+    "check": "node tools/check-package.mjs && node tools/check-public.mjs && node tools/check-plugin.mjs",
+    "prepublishOnly": "npm run verify",
+    "check:public": "node tools/check-public.mjs",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint .",
+    "verify": "npm run format:check && npm run lint && npm test && npm run check"
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.1.0",
@@ -27,12 +42,32 @@
     "zod": "4.6.5"
   },
   "devDependencies": {
-    "@modelcontextprotocol/client": "2.1.0"
+    "@eslint/js": "10.0.1",
+    "@modelcontextprotocol/client": "2.1.0",
+    "ajv": "8.20.0",
+    "eslint": "10.11.0",
+    "globals": "17.12.0",
+    "prettier": "3.9.9"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "publishConfig": {
     "access": "public",
     "tag": "beta",
     "registry": "https://registry.npmjs.org/"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PulsarInteractive/geniustasker-agent-tools.git"
+  },
+  "homepage": "https://github.com/PulsarInteractive/geniustasker-agent-tools#readme",
+  "bugs": {
+    "url": "https://github.com/PulsarInteractive/geniustasker-agent-tools/issues"
+  },
+  "keywords": [
+    "geniustasker",
+    "mcp",
+    "cli",
+    "agent-skills",
+    "codex"
+  ]
 }