@pulsarinteractive/geniustasker 0.1.0-beta.11 → 0.1.0-beta.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +14 -1
  3. package/docs/ARCHITECTURE.md +15 -13
  4. package/docs/CHATGPT.md +6 -0
  5. package/docs/CLI.md +153 -5
  6. package/docs/INTEGRATIONS.md +25 -2
  7. package/docs/MEMORY.md +9 -0
  8. package/docs/WORKFLOWS.md +14 -0
  9. package/examples/codex.toml +1 -1
  10. package/examples/mcp.json +1 -1
  11. package/mcp.json +1 -1
  12. package/package.json +2 -2
  13. package/plugin.json +1 -1
  14. package/remote/tool-catalog.json +296 -1
  15. package/remote/workflows.json +53 -2
  16. package/skills/geniustasker/SKILL.md +15 -1
  17. package/skills/geniustasker/references/agent-runs.md +144 -0
  18. package/skills/geniustasker/references/host-events.md +116 -0
  19. package/skills/geniustasker/references/importance.md +90 -0
  20. package/skills/geniustasker/references/metric-goals.md +143 -0
  21. package/skills/geniustasker/references/metrics-observations.md +184 -0
  22. package/skills/geniustasker/references/metrics.md +136 -0
  23. package/skills/geniustasker/references/protocols.md +156 -0
  24. package/skills/geniustasker/references/updates.md +31 -0
  25. package/skills/geniustasker-graph/SKILL.md +10 -0
  26. package/skills/geniustasker-memory/SKILL.md +19 -6
  27. package/skills/geniustasker-memory/references/knowledge-workflows.md +42 -0
  28. package/skills/geniustasker-planning/SKILL.md +6 -1
  29. package/src/changes.mjs +3 -5
  30. package/src/cli.mjs +108 -14
  31. package/src/command-catalog.mjs +849 -562
  32. package/src/command-input-schemas.d.mts +8 -0
  33. package/src/command-input-schemas.mjs +1021 -0
  34. package/src/commands.mjs +78 -25
  35. package/src/mcp.mjs +48 -20
  36. package/src/protocols.mjs +122 -0
  37. package/src/resources.mjs +98 -0
  38. package/src/run-events.mjs +145 -0
  39. package/src/update-runtime.mjs +169 -0
  40. package/src/update.mjs +306 -0
@@ -0,0 +1,184 @@
1
+ # Record, correct or void a metric observation
2
+
3
+ First read the [definition workflow](metrics.md), current identity, capabilities
4
+ and the exact definition. Use `metrics:read` to inspect it and `metrics:write`
5
+ for the requested mutation. The server also checks current native rights:
6
+ personal data belongs to the connected owner, while project observations use
7
+ the definition's writer policy. A grant never bypasses project opt-in or
8
+ membership. Do not add yourself to `writers` to work around a refusal.
9
+
10
+ ## Read the consolidated result
11
+
12
+ Read the metric definition (`metrics` / `personalMetrics`) and inspect
13
+ `data.summary` before requesting observation history. This server-maintained
14
+ summary updates atomically with the source observation; it excludes voided
15
+ observations and all historical correction snapshots. It is lifetime-only.
16
+ A title such as “Weekly revenue” does not turn its summary into a current-week
17
+ aggregate. Requested [metric goals](metric-goals.md) have their own lifetime or
18
+ fixed-window evaluation. Discover that separate capability before using it; an
19
+ observation command never creates a goal or installs an arbitrary trigger.
20
+
21
+ - `activeCount` counts current, non-voided observations. It is distinct from
22
+ `observationCount`, which retains the count of recorded source observations.
23
+ - `sumUnits`, `numeratorUnits` and `denominatorUnits` are exact integer **strings**
24
+ in units of `10^-configuration.precision`. For precision 2, `"425"` means
25
+ 4.25 units. Do not parse large totals as JavaScript `Number` or send these
26
+ strings back as new observations; keep exact integer/decimal arithmetic when
27
+ calculation is necessary.
28
+ - `value` is a nullable decimal **string**, already formatted at the configured
29
+ precision. Mean and Ratio round half away from zero for display. It is not a
30
+ JSON number or an unrounded threshold result. Use it for presentation without
31
+ another floating-point conversion; do not infer exact threshold satisfaction
32
+ from its rounded digits.
33
+ - `latest` identifies the latest active evidence with `observationId`,
34
+ `observedAt` and `measurement`. Gauge/Latest uses observation time, not arrival
35
+ time. A late older sample can change a Sum, Mean or Ratio without becoming the
36
+ latest observation. A correction or void can change which evidence is latest.
37
+
38
+ For an empty active set, `value` and `latest` are null. This is “no active
39
+ measurement,” not zero. A measured zero can instead have `activeCount > 0` and
40
+ `value:"0.00"`. A completely missing `summary` on a legacy definition means
41
+ unknown, not an empty set: never fabricate zero fields or reconstruct and write
42
+ the summary through client commands. If a write returns
43
+ `metric_summary_rebuild_required` (503), retain its immutable operation and
44
+ report that server repair is required; do not keep retrying or create another
45
+ metric to bypass it.
46
+
47
+ Freshness compares `summary.latest.observedAt` with the current time and
48
+ `configuration.freshnessSeconds`. Do not use definition `updated`, correction
49
+ arrival time or the time you fetched the page to claim fresh evidence. A null
50
+ freshness setting means no expected cadence was configured, not that all data
51
+ is always fresh. If latest is null, there is no active evidence to assess.
52
+ Late arrivals retain their source date; never replace it with now to make a
53
+ summary appear current.
54
+
55
+ ## Choose the actual evidence
56
+
57
+ | Definition kind | `measurement` meaning |
58
+ | --------------- | ----------------------------------------------------------------------------------- |
59
+ | `Gauge` | `value` is the absolute level; `numerator` and `denominator` are null. |
60
+ | `Counter` | `value` is a signed contribution, not a running total; other fields are null. |
61
+ | `Ratio` | `value` is null; `numerator` is nonnegative and `denominator` is strictly positive. |
62
+
63
+ For example, a cumulative provider counter increasing from 100 to 103 is a
64
+ Gauge value of 103 **or**, for an explicitly defined increment metric with a
65
+ verified previous baseline, a Counter contribution of 3. It is never a Counter
66
+ contribution of 103. A negative Counter contribution can represent a real
67
+ reversal; correcting a wrong entry instead uses `metric.correct` so its cause
68
+ and previous value remain visible. Missing data is not a measured zero.
69
+
70
+ A Ratio's result uses the configured scale and sums of numerator and denominator.
71
+ Do not submit a percentage as `value`, or average rates with unequal denominators.
72
+ Do not calculate a global result from a partial history page. Corrections are
73
+ previous snapshots and must never be added to the observations; voided
74
+ observations must not be treated as active evidence.
75
+
76
+ Keep numbers in the definition's unit and precision. Magnitudes are bounded by
77
+ the current schema (currently 1,000,000,000); nonfinite numbers and invalid
78
+ denominators are not observations. Do not silently round or convert ambiguous
79
+ source units. Ask or clarify the definition when the source does not fit it.
80
+
81
+ ## Record once
82
+
83
+ `metric.record` creates a new observation UUID with `expectedRevision:null`.
84
+ Its `data` contains `metricId`, the definition's current `measurementVersion`,
85
+ `sourceKey`, `sourceLabel`, `observedAt` and all three `measurement` fields.
86
+ The envelope ID is the **observation ID**, not the definition ID.
87
+
88
+ `sourceKey` is the stable event identity within that metric, for example a
89
+ provider record ID or a specific period's identifier. Preserve the observation
90
+ UUID and key in the producer's own mapping. Do not derive either from retry time
91
+ or translated text. Labels may be localized; identifiers must stay unchanged.
92
+ Neither field should contain credentials, signed download URLs or raw private
93
+ logs. A later independent observation gets its own event identity.
94
+
95
+ `observedAt` is the source observation time with an explicit timezone, not
96
+ arrival time. A late observation retains its real date. Do not substitute now
97
+ to evade freshness checks; the server bounds future skew. Never guess a missing
98
+ measurement, timestamp or source period.
99
+
100
+ Example `data` for a Gauge observation:
101
+
102
+ ```json
103
+ {
104
+ "metricId": "00000000-0000-4000-8000-000000000001",
105
+ "measurementVersion": 1,
106
+ "sourceKey": "finance:week-2026-46",
107
+ "sourceLabel": "Weekly sales export",
108
+ "observedAt": "2026-11-15T23:00:00Z",
109
+ "measurement": { "value": 1250.5, "numerator": null, "denominator": null }
110
+ }
111
+ ```
112
+
113
+ Example `data` for a different definition configured as Ratio:
114
+
115
+ ```json
116
+ {
117
+ "metricId": "00000000-0000-4000-8000-000000000002",
118
+ "measurementVersion": 1,
119
+ "sourceKey": "support:week-2026-46",
120
+ "sourceLabel": "Reviewed support outcomes",
121
+ "observedAt": "2026-11-15T23:00:00Z",
122
+ "measurement": { "value": null, "numerator": 18, "denominator": 20 }
123
+ }
124
+ ```
125
+
126
+ Do not send a batch hidden in one field. Each observation is one normal command,
127
+ using the shared account request and storage quotas. Preparing a local command
128
+ persists its immutable journal before sending; hosted preparation returns the
129
+ exact command to retain. On an uncertain response, retry that same operation ID,
130
+ `issuedAt` and body under the same identity. This is separate from source-event
131
+ deduplication: creating a new operation or UUID does not make an already used
132
+ `sourceKey` a new observation. On duplicate-source refusal, reconcile the saved
133
+ mapping and current record; do not alter the key to get around it.
134
+
135
+ ## Correct or void with a reason
136
+
137
+ Read the current observation by ID, along with its definition. `metric.correct`
138
+ targets that observation UUID and its current revision, never the definition's
139
+ revision. Supply a complete replacement measurement and observedAt, plus a
140
+ concrete reason. It cannot change metricId, sourceKey or sourceLabel. The server
141
+ retains the previous snapshot and attributes the change to the real caller.
142
+
143
+ ```json
144
+ {
145
+ "observedAt": "2026-11-15T23:00:00Z",
146
+ "measurement": { "value": 1200.5, "numerator": null, "denominator": null },
147
+ "reason": "The verified export excluded a refunded sale that the initial amount included."
148
+ }
149
+ ```
150
+
151
+ Use `metric.void` when the evidence must be invalidated, with the current
152
+ observation revision and a reason:
153
+
154
+ ```json
155
+ { "reason": "This source export was generated from the wrong reporting period." }
156
+ ```
157
+
158
+ Void does not delete the observation or its audit trail. Do not clear source
159
+ keys, forge `voided` or write directly to correction collections. A conflict
160
+ means reread and decide again; do not overwrite a concurrent correction. If a
161
+ paused/archived definition or current writer policy refuses an operation, report
162
+ the refusal rather than changing settings implicitly.
163
+
164
+ ## Bounded reads and truthful completion
165
+
166
+ ```sh
167
+ geniustasker commands describe --kind metric.record --json
168
+ geniustasker commands describe --kind metric.correct --json
169
+ geniustasker metrics list --scope project:PROJECT --collection metricObservations --id OBSERVATION_UUID --json
170
+ geniustasker metrics list --scope project:PROJECT --collection metricObservations --metric-id METRIC_UUID --json
171
+ geniustasker metrics list --scope project:PROJECT --collection metricCorrections --metric-id METRIC_UUID --json
172
+ ```
173
+
174
+ Use the personal-prefixed collections for the connected personal scope. Every
175
+ page uses normal read admission; carry epoch/checkpoint/after and the exact
176
+ `metricId` filter unchanged. The equality filter applies only to observations
177
+ and corrections. Filtered reads return `changeCursor:null`; do not start a
178
+ filtered change stream. Only an unfiltered completed inventory supplies a
179
+ collection change cursor. There is no implicit full export or complex search.
180
+ A correction row includes `observationId`,
181
+ `previousRevision` and replacement attribution; it describes previous evidence,
182
+ not another event to count. Report the saved observation/correction and its
183
+ receipt. Do not claim goal progress, a trigger or a running collector unless
184
+ that separate capability is available and its result has actually been verified.
@@ -0,0 +1,136 @@
1
+ # Custom metric definitions
2
+
3
+ Use this workflow to define a measurement for the connected person or one
4
+ GeniusTasker project. Discover live capabilities first: `metrics:read` and
5
+ `metrics:write` are independent permissions. Existing task/goal grants do not
6
+ include them. Project configuration also requires the owner or administrator
7
+ and agent contributions enabled. A refusal is not permission to use private APIs.
8
+
9
+ Definition creation does not itself record a value. When capabilities advertise
10
+ `metric.record`, `metric.correct` and `metric.void`, use the
11
+ [observation workflow](metrics-observations.md) to record real evidence and retain
12
+ its corrections. These operations do not start a collector or link a goal.
13
+ When requested and advertised, use the separate [metric goal workflow](metric-goals.md)
14
+ to evaluate a target against the same scope’s metric. Existing YouTube/Spotify metrics are separate. Feature
15
+ activation and package installation are separate: use only what the current
16
+ server advertises.
17
+
18
+ ## Read the right scope
19
+
20
+ Get `actor.ownerId` from current identity, never from a profile ID, name or old
21
+ session. For a personal definition use `personal:<actor.ownerId>`; for a project
22
+ definition use its discovered `project:<id>` scope. Consent to personal metrics
23
+ is a separate resource choice; it does not expose other personal account data.
24
+
25
+ ```sh
26
+ geniustasker metrics list --scope personal:OWNER --json
27
+ geniustasker metrics list --scope project:PROJECT --json
28
+ geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
29
+ geniustasker metrics list --scope project:PROJECT --collection metricObservations --json
30
+ geniustasker metrics list --scope personal:OWNER --collection personalMetricCorrections --json
31
+ geniustasker commands describe --kind metric.create --json
32
+ geniustasker workflow show --topic metrics --json
33
+ ```
34
+
35
+ Use the chosen environment/context consistently, including
36
+ `--environment production` for production data. `resources list` also supports
37
+ `metrics` in project scopes and `personalMetrics` in the connected personal
38
+ scope. In MCP prefer `tasker_read_metrics` with that same collection and scope.
39
+ Select `metricObservations` / `personalMetricObservations` for the current
40
+ observations, or `metricCorrections` / `personalMetricCorrections` for previous
41
+ snapshots. Linked goals use `metricGoals` / `personalMetricGoals`; these accept
42
+ an exact goal `id`, not the history-only `metricId` filter. The default CLI collection remains definitions for compatibility.
43
+ Read one page at a time; carry `after`, `epoch` and `checkpoint` unchanged for
44
+ continuation. Take the epoch from the returned page, including an empty one.
45
+ Use an exact ID read before editing and preserve unmodified configuration.
46
+ For observation/correction collections, `--metric-id METRIC_UUID` (MCP
47
+ `metricId`) selects one exact definition. Preserve that filter on every page;
48
+ filtered results have `changeCursor:null` and cannot start a filtered change
49
+ stream. Date-window and compound query filters are not exposed. Do not invent
50
+ query parameters or load every page implicitly; request further bounded pages
51
+ only when needed and state when a result is partial.
52
+
53
+ ## Choose a useful meaning
54
+
55
+ For an existing metric's consolidated result, first read the definition's
56
+ `summary` with `metrics` or `personalMetrics`. This avoids scanning observations
57
+ just to obtain a total. The server updates it atomically with each accepted
58
+ record, correction or void. It covers the metric's **entire recorded lifetime**,
59
+ not a week, month or rolling window, even if the title mentions a period.
60
+ For exact numeric fields, missing values and freshness, read
61
+ [the summary rules](metrics-observations.md#read-the-consolidated-result).
62
+
63
+ | Meaning | Configuration | Avoid |
64
+ | ----------------------------------------------- | ------------------ | ------------------------------------------------ |
65
+ | Current level, such as audience size | `Gauge` + `Latest` | Summing repeated cumulative totals |
66
+ | Average of comparable samples | `Gauge` + `Mean` | Averaging unlike units or unequal weighted rates |
67
+ | Additive contributions, such as completed units | `Counter` + `Sum` | Overlapping periods and repeated contributions |
68
+ | Numerator/denominator measure | `Ratio` + `Ratio` | Unweighted averages of percentages |
69
+
70
+ Explain the unit, data source, interval and interpretation in the description.
71
+ Ask only for an ambiguity that changes the meaning. Never invent values or
72
+ claim an approximation is an observed result. The machine key stays stable;
73
+ write title and description naturally in the user's language. Do not translate
74
+ keys, IDs, API property names or enum values.
75
+
76
+ `precision` is 0–6. `ratioScale` is 1 or 100 for a Ratio, and 1 otherwise.
77
+ `freshnessSeconds` is null or 60–31536000; it describes expected freshness and
78
+ does not schedule collection. `writers` is empty for a personal definition.
79
+ Project writers are current approved member user IDs, not agent profile IDs;
80
+ they do not grant project administration or additional API permissions.
81
+
82
+ ## Prepare and persist
83
+
84
+ `metric.create` and `metric.update` take this complete `data` shape (example in
85
+ French). Inspect command help for the current limits; do not send the internal
86
+ `action` field or server-owned creator, count, version or attribution fields.
87
+
88
+ ```json
89
+ {
90
+ "configuration": {
91
+ "key": "weekly_revenue",
92
+ "title": "Chiffre d’affaires hebdomadaire",
93
+ "description": "Montant total pour une semaine complète, en euros. La source et la période seront précisées lors de la collecte.",
94
+ "kind": "Gauge",
95
+ "aggregation": "Latest",
96
+ "unit": "EUR",
97
+ "precision": 2,
98
+ "ratioScale": 1,
99
+ "freshnessSeconds": 604800,
100
+ "writers": [],
101
+ "paused": false,
102
+ "archived": false
103
+ }
104
+ }
105
+ ```
106
+
107
+ For creation choose and retain one lowercase UUID as `id`, the scope's current
108
+ `epoch`, `expectedRevision:null`, and `kind:"metric.create"`. For update read the
109
+ existing UUID/revision and send `kind:"metric.update"` with the complete updated
110
+ configuration. The key cannot change. A duplicate key is a reason to reread and
111
+ reuse the intended definition, not to create several nearly identical entries.
112
+
113
+ Local CLI: `commands prepare --file draft.json --json`, then
114
+ `commands retry --operation OPERATION_UUID --json`. Local MCP: prepare with
115
+ `tasker_prepare_command`, then retry the returned operation or execute the
116
+ immutable request with `tasker_edit_metrics`. The dedicated tool uses the same
117
+ journal and normal server admission. Hosted MCP has no local journal: retain the
118
+ exact command returned by preparation and pass it to `tasker_edit_metrics`.
119
+
120
+ After uncertainty retain the exact operation ID, time and body. Respect retry
121
+ delays. After a revision conflict, reread and decide whether a new edit is still
122
+ appropriate. Do not automatically replace the user's configuration or broaden
123
+ access. A definition receipt proves configuration persistence, not collection or
124
+ progress toward a goal.
125
+
126
+ ## Preserve existing meaning
127
+
128
+ Changing kind, aggregation, unit, precision or ratio scale changes the meaning
129
+ of samples. The server refuses it when observations exist. Do not silently
130
+ convert a definition to another unit or manufacture a zero observation count.
131
+ Descriptive changes do not increment measurement semantics.
132
+
133
+ Archive through `configuration.archived:true` with a current revision when the
134
+ definition should be retained. `metric.delete` takes empty `data` and a current
135
+ revision; it is refused when observations exist. No bulk ingestion, history
136
+ deletion or custom-goal operation is implied by these definition commands.
@@ -0,0 +1,156 @@
1
+ # Reuse a task protocol
2
+
3
+ Use this workflow when the user wants a reusable procedure with several tasks,
4
+ dependencies, acceptance criteria and deliberately selected importance. A
5
+ protocol creates tracked work; it does not execute the work or run an agent.
6
+ For a few unrelated tasks, ordinary task commands remain sufficient.
7
+
8
+ ## Find the right version
9
+
10
+ Read identity, capabilities, the selected project and its relevant configuration.
11
+ Discover `taskTemplates`, `protocolInstances` and `protocol.*` commands before
12
+ using them. Protocols target Details projects. A legacy template containing only
13
+ a name and description is not a published protocol. Existing project agent
14
+ contributions, current membership and the appropriate grants must permit writes.
15
+
16
+ Read the selected `taskTemplates` version, its `protocolDefinition`, family,
17
+ version and digest. Preserve its step keys; they determine task identities.
18
+ Check project features, dependencies, members and the user's intended outcome.
19
+ Do not infer that an administrative role or a task assignment authorizes an
20
+ unrelated external action.
21
+
22
+ Publishing requires project administration and `tasks:write`. Use
23
+ `protocol.publish` with a new UUID, null revision and
24
+ `data: {definition, previousVersionId}`. Null starts a family; otherwise use the
25
+ latest immutable version ID. Never patch a published version in place or
26
+ silently convert an older template. Read command help for the current schema.
27
+
28
+ ## Inspect the exact data schema
29
+
30
+ Use `geniustasker commands describe --kind protocol.publish --json` or local /
31
+ hosted `tasker_command_help` with `{"kind":"protocol.publish"}` before preparing
32
+ it. The four protocol commands expose nested field schemas and required fields.
33
+ Local help is offline; it does not claim the account has access. The server still
34
+ checks semantic rules such as valid members, actual dates and dependency cycles.
35
+ Never send the internal `action` field.
36
+
37
+ A minimal `protocol.publish` **data** object (the immutable command envelope also
38
+ needs the selected project, current epoch, a new version UUID and null revision):
39
+
40
+ ```json
41
+ {
42
+ "definition": {
43
+ "formatVersion": 1,
44
+ "name": "Verify a small delivery",
45
+ "description": "A reusable verification task.",
46
+ "variables": [],
47
+ "steps": [
48
+ {
49
+ "key": "verify",
50
+ "title": "Verify the requested behavior",
51
+ "description": "Check the agreed acceptance criteria.",
52
+ "kind": "Ticket",
53
+ "parent": null,
54
+ "dependencies": [],
55
+ "importance": "Normal",
56
+ "importanceReason": "",
57
+ "delivery": { "push": "silent", "recap": true, "animation": "silent" },
58
+ "acceptance": ["The requested behavior has been verified."],
59
+ "ownerVariable": null,
60
+ "dueAfterDays": null
61
+ }
62
+ ]
63
+ },
64
+ "previousVersionId": null
65
+ }
66
+ ```
67
+
68
+ Adapt the work to the request; this is a schema example, not a prescribed workflow.
69
+ An `ownerVariable` references a declared user variable; null assigns the creator.
70
+ Parent/dependency values reference other step keys, never newly guessed task IDs.
71
+ A child kind and its parent must form a supported Epic → Ticket → Subtask chain.
72
+
73
+ ## Bind and preview
74
+
75
+ Choose one lowercase UUID for `instanceId` and retain it. Bind only declared
76
+ variables: text, number, boolean, current user/member ID or date. Missing required
77
+ values need relevant user information. Preserve `false` and `0`; neither means
78
+ missing. Values are literal data, not expressions or agent instructions.
79
+
80
+ Capture an explicit timezone-qualified `anchor` once. `dueAfterDays` means elapsed
81
+ 24-hour days from that anchor, not a local calendar or recurring schedule. Reuse
82
+ the same anchor on every preview page and in the eventual start command.
83
+
84
+ `tasker_protocol_preview` and `protocols preview --file` take:
85
+
86
+ ```json
87
+ {
88
+ "scope": "project:PROJECT_ID",
89
+ "protocolVersionId": "11111111-1111-4111-8111-111111111111",
90
+ "bindings": {
91
+ "instanceId": "22222222-2222-4222-8222-222222222222",
92
+ "scope": "project:PROJECT_ID",
93
+ "epoch": "EPOCH_FROM_CURRENT_READ",
94
+ "anchor": "2026-11-16T09:00:00+01:00",
95
+ "values": {}
96
+ }
97
+ }
98
+ ```
99
+
100
+ Replace all example identifiers and the date with the actual project, version,
101
+ epoch and intended timing. Populate `values` from the chosen definition.
102
+
103
+ Preview requires `tasks:read`; it creates neither an instance nor tasks. Each
104
+ call consumes the normal read budget and returns at most 20 steps. When needed,
105
+ continue with `after: nextAfter` and the original returned `digest`, keeping the
106
+ version and every binding unchanged. Stop at `nextAfter: null`. Never claim
107
+ unread pages were inspected; changed context or lost access needs reconciliation.
108
+
109
+ Review the outcome, owners, dates, acceptance criteria, dependency structure and
110
+ importance. [Importance](importance.md) measures impact, independently of urgency
111
+ and hierarchy. Important/Critical need a concrete reason. Delivery preferences
112
+ request or suppress attention; a request cannot bypass recipient settings.
113
+
114
+ ## Materialize only the requested work
115
+
116
+ If the user asked to create this work, use the normal immutable command workflow.
117
+ Otherwise show the relevant preview and await that decision. No preview grants
118
+ write access or authorizes a later changed plan.
119
+
120
+ 1. Prepare `protocol.start` with `id: bindings.instanceId`, `expectedRevision:
121
+ null`, the same scope/epoch, and `data: {protocolVersionId, bindings}`.
122
+ 2. Execute that exact prepared operation, then read the resulting
123
+ `protocolInstances` record for its current revision, digest and `appliedCount`.
124
+ 3. Prepare `protocol.apply` against that instance and revision with
125
+ `data: {digest, from: appliedCount, count: 20}` or a smaller intended batch.
126
+ One call creates at most 20 steps through ordinary authority and quota checks.
127
+ 4. Read the confirmed result before preparing another batch. Continue only
128
+ within the requested work; there is no automatic apply loop in the client.
129
+
130
+ An uncertain reply requires replaying the same operation, not incrementing the
131
+ cursor or creating a fresh ID. After a definitive conflict, reread and reconcile.
132
+ Do not bypass expired/revoked access, identity binding, an ID collision or a
133
+ human-owned importance decision by using another transport or recreating tasks.
134
+ The creating user or a current project administrator may continue or cancel an
135
+ instance. The same user may continue under another profile only within that
136
+ profile's current grants; each new command rechecks access. An uncertain operation
137
+ remains bound to its original command identity and cannot be moved to another
138
+ profile or session. Resolve its outcome before preparing a new batch.
139
+
140
+ `Applied` means the tasks were materialized. It says nothing about completed
141
+ work, earned XP or delivered notifications. `protocol.cancel` with the current
142
+ revision stops remaining materialization; it preserves already created tasks.
143
+ Do not delete them as an implicit rollback. Instance counters, state and
144
+ provenance are server-owned.
145
+
146
+ CLI example for inspection, without creation:
147
+
148
+ ```sh
149
+ geniustasker workflow show --topic protocols --json
150
+ geniustasker protocols preview --file protocol-preview.json --context work --json
151
+ geniustasker commands describe --json
152
+ ```
153
+
154
+ CLI/local MCP preparation saves a private journal. Hosted ChatGPT preparation
155
+ returns the immutable command object; retain it and pass it to `tasker_edit_tasks`.
156
+ Both share the same account budget, membership and project permissions.
@@ -0,0 +1,31 @@
1
+ # CLI updates
2
+
3
+ Use `geniustasker update check --json` when checking package freshness. It reads
4
+ the official npm registry anonymously and does not read an account or consume its
5
+ API quota. The installed release selects beta or stable automatically; use
6
+ `--channel beta` or `--channel stable` only when that channel change is intended.
7
+ An older registry version is not a downgrade instruction.
8
+
9
+ When the user has requested an update, stop the local MCP server and let active
10
+ CLI commands finish, then run `geniustasker update install --json` in a terminal.
11
+ It updates only the current global npm installation. If the host uses an npx
12
+ version pin, a project dependency, a source checkout or another package manager,
13
+ update that installation through its own workflow instead; do not replace an
14
+ unrelated global package or change the host configuration without authorization.
15
+ Restart the MCP host after installation. This is not a hosted connector update.
16
+
17
+ The updater preserves credentials and immutable journals. An uncertain operation
18
+ stays uncertain: inspect it and retry the same operation only when the underlying
19
+ task calls for it. Do not reset authentication, remove journals or automatically
20
+ retry domain commands because a package was updated.
21
+
22
+ `update_runtime_busy` means another CLI/MCP process or an installer still owns
23
+ the installation. Wait or close it; never kill another task to install an update.
24
+ A crashed installer may leave an `install.lock` directory. Recover it only after
25
+ confirming that the installer and all clients have stopped, using the procedure
26
+ in [CLI updates](../../../docs/CLI.md#updates). `update_install_unconfirmed` needs
27
+ inspection of the installed version before retrying; it is not a success receipt.
28
+
29
+ Automatic discovery never runs from MCP or JSON calls. For terminal sessions,
30
+ `GENIUSTASKER_NO_UPDATE_CHECK=1` disables it. A registry outage must not interrupt
31
+ the user's actual work or trigger repeated checks.
@@ -10,6 +10,16 @@ do not load every graph at startup. Search nodes, inspect `nodeIndex`, then use
10
10
  `tasker_graph` around a selected node. Respect `truncated`: an incomplete
11
11
  neighborhood cannot prove a relation is absent. Read full records before edits.
12
12
 
13
+ Graph creation, node/edge changes and delegated Graph reads/search/exploration
14
+ require the acting user's Starter or Pro plan as well as the existing resource
15
+ grant. A paid space owner does not upgrade another reader. Document pages,
16
+ attachments and document references remain independent capabilities.
17
+ On `memory_graph_premium_required`, stop Graph calls; another tool, profile or
18
+ connection is not a workaround. After downgrade, the user can still inspect
19
+ existing content through ordinary application sync and personal-data export.
20
+ Offer document-only work when it satisfies the request; do not copy Graph data
21
+ into pages to evade the restriction.
22
+
13
23
  Each node owns its title, type, notes and optional resource thumbnail. Each edge
14
24
  has a source, target, typed relation and certainty. Prefer precise relation names
15
25
  and mark proposed connections as proposals. Preserve existing identities instead
@@ -6,7 +6,10 @@ description: Read and maintain GeniusTasker Memory documents and Graph relations
6
6
  Memory belongs to the account and is independent of projects. Use the user's
7
7
  selected context and environment; discover identity and capabilities first.
8
8
  If no session exists, ask the user to run `geniustasker auth login --context work`
9
- in their terminal. The browser lets them select resources and permissions.
9
+ in their terminal with the intended environment. The beta defaults to development;
10
+ TestFlight data requires `--environment production` at login and on subsequent
11
+ CLI/MCP invocations. Use a distinct context; its name alone does not select an
12
+ environment. The browser lets them select resources and permissions.
10
13
  Do not collect passwords or tokens, approve your own consent, or edit credentials.
11
14
 
12
15
  ## Navigate without loading the entire corpus
@@ -44,11 +47,16 @@ A new memory uses one UUID v4 for root ID, scope suffix and initial epoch. Updat
44
47
  and deletes use a freshly read revision. Destructive changes require the user's
45
48
  actual authorization; read access never implies write access.
46
49
 
47
- Prepare a complete immutable operation using `tasker_prepare_command`, then send
48
- it with `tasker_retry_command` and the returned operation ID. CLI equivalents are
49
- `commands prepare --file draft.json` and `commands retry --operation ID`.
50
- After a timeout retry the exact retained operation. After a revision conflict,
51
- reread and prepare a new edit. Never change the body under an existing ID.
50
+ Prepare a complete immutable operation using `tasker_prepare_command`. In local
51
+ MCP, execute it with `tasker_retry_command` and the returned operation ID; the CLI
52
+ equivalents are `commands prepare --file draft.json` and
53
+ `commands retry --operation ID`. Hosted ChatGPT has no local operation journal:
54
+ retain the returned command object and send it through the discovered Memory edit
55
+ tool (`tasker_edit_memory`), unchanged after an uncertain result. Do not call a
56
+ local-only retry tool in the connector. After a revision conflict, reread and
57
+ reconcile the other contribution before preparing a new operation; never replace
58
+ the complete current page with an older snapshot. See the multi-agent procedure
59
+ in [focused knowledge workflows](references/knowledge-workflows.md).
52
60
 
53
61
  For authorized imports, keep a resumable local journal and source hashes; split
54
62
  pages to the advertised bounds, avoid duplicates, preserve editorial authority,
@@ -64,6 +72,11 @@ deployments may not expose them. Nodes and edges live in a memory scope. Read
64
72
  (`graph explore`) around a selected node rather than reading the entire graph.
65
73
  `truncated` means the result is incomplete. Never infer absent relations from it.
66
74
 
75
+ Graph creation, edits and delegated Graph reads/search/exploration require
76
+ Starter or Pro for the acting user, plus the resource grant. Documents and their
77
+ attachments remain independent. On `memory_graph_premium_required`, stop Graph
78
+ calls; do not switch tools, profiles or copy it into documents to bypass the tier.
79
+
67
80
  Each node owns its editable text; references contain only scope, pageId and an
68
81
  optional blockId. Use `tasker_reference` (`memory resolve`) for linked content.
69
82
  Access to Graph does not grant access to its references, including shared memories.
@@ -12,6 +12,12 @@ with the original epoch and checkpoint, including empty pages with a cursor.
12
12
  An unavailable source is not an empty source. Report the gap without changing
13
13
  accounts, permissions or the user's sharing settings.
14
14
 
15
+ Search is lexical, not a semantic ranking or a corpus-wide reasoning engine.
16
+ It matches up to twelve word prefixes together in one Memory and returns one
17
+ bounded page. If the result is insufficient, refine the words or make another
18
+ targeted call. Each call has normal authorization and usage accounting; do not
19
+ simulate an unlimited search with parallel calls over every Memory.
20
+
15
21
  ## Explore Graph progressively
16
22
 
17
23
  Use node search or `nodeIndex` to find a starting node. Call `tasker_graph` with
@@ -55,3 +61,39 @@ and source provenance. Prepare one immutable command and retain its operation ID
55
61
  retry that exact operation after a timeout. A revision conflict requires a new
56
62
  read and a new operation. Report what changed, what was verified, and what
57
63
  remains inaccessible or incomplete.
64
+
65
+ ## Cooperate without overwriting another agent
66
+
67
+ Two agents can read the same revision. A successful edit by one makes the
68
+ other's older update stale, even when their intended changes affect different
69
+ blocks. There is no automatic document merge and no exclusive Memory run lease.
70
+ Use separate profiles for attribution, not to avoid limits or gain access.
71
+
72
+ 1. Read the full page or node and retain its epoch, revision and stable block IDs.
73
+ Identify the requested change separately from the rest of the document.
74
+ 2. Prepare one immutable operation. After a timeout, establish that operation's
75
+ outcome before sending any replacement; a fresh read alone cannot settle an
76
+ uncertain command.
77
+ 3. If the service definitively reports `revision_conflict`, read the current
78
+ record again. Keep the other agent's contribution and all unrelated IDs,
79
+ references, source provenance and access fields.
80
+ 4. If the changes are compatible, apply only the intended edit to the new full
81
+ content and prepare a **new operation ID** using the newly read revision.
82
+ For conflicting claims or incompatible edits, leave the current record intact
83
+ and present the conflict or an explicitly labeled proposal to the user. Do not
84
+ decide that your version is authoritative because it came from an agent.
85
+ 5. Read back the saved result. Report the source ID/revision and the verified
86
+ change. Refresh relevant documentation mirrors after the source is confirmed.
87
+
88
+ `sourceId`, `authority`, `provenance` and `metadataJson` describe the content;
89
+ they are not verified identity, permission or proof of factual correctness.
90
+ Preserve original attribution and distinguish evidence from a new proposal.
91
+ The read-only `lastAgentActor`, when available on a page, node or edge, identifies
92
+ the server-verified latest agent editor (`ownerId`, `profileId`, `profileName`).
93
+ Never send or forge it in an edit. A human edit clears it; an older record without
94
+ the field has unknown agent attribution, not proof of human authorship. This
95
+ latest-editor snapshot is not a complete audit history or a claim that its
96
+ content has been fact-checked.
97
+ For local CLI/MCP retain the journal operation ID. For hosted ChatGPT retain the
98
+ complete prepared command and retry it with the discovered Memory edit tool;
99
+ the host cannot read a local journal or repository filesystem.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: geniustasker-planning
3
- description: Use when the user asks to plan GeniusTasker tickets in a backlog or sprint, manage projects/sprints/recurrences/documents, customize project tags or saved filters, or review task dependencies.
3
+ description: Use when the user asks to plan GeniusTasker tickets, reuse a task protocol, manage projects/sprints/recurrences/documents, customize project tags or saved filters, or review task dependencies.
4
4
  ---
5
5
 
6
6
  # Plan tasks and shared project workflows
@@ -9,6 +9,11 @@ Inspect identity and capabilities, then read `tasker_workflow` with
9
9
  `topic: planning` for the current transport and product instructions.
10
10
 
11
11
  Read the project configuration, relevant tasks and existing sprint/workflow IDs.
12
+ For reusable multi-task procedures, read [Task protocols](../geniustasker/references/protocols.md)
13
+ and `tasker_workflow` with `topic: protocols`. Preview creates no work; applying
14
+ the requested procedure uses explicit journaled batches with current revisions.
15
+ When creating or reassessing tasks, use [task importance](../geniustasker/references/importance.md)
16
+ to distinguish impact from urgency and preserve human-owned classifications.
12
17
  Use ticket.plan for placement changes and preserve its root and per-task revision
13
18
  checks. Project tags and saved filters are shared configuration; do not turn an
14
19
  example label into a global requirement for every project.