@pulsarinteractive/geniustasker 0.1.0-beta.12 → 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.
@@ -0,0 +1,143 @@
1
+ # Link a goal to measured evidence
2
+
3
+ Use this workflow only for a requested goal and when live capabilities advertise
4
+ `metric.goal.create`, `metric.goal.update` and `metric.goal.delete`. A definition
5
+ or observation command never creates a goal implicitly. Read the
6
+ [definition](metrics.md) and [observation](metrics-observations.md) workflows first.
7
+ Existing recurring task goals and YouTube/Spotify goals remain separate.
8
+
9
+ ## Read and explain the source
10
+
11
+ Use `metrics:read` / `metrics:write`; task and ordinary goal grants do not include
12
+ these permissions. Configuration also requires current project owner/admin
13
+ rights or the connected personal owner. Use `actor.ownerId` from identity for
14
+ `personal:<owner>`, never another account or a profile ID. The source definition
15
+ must exist in the **same scope** and express the intended unit and aggregation.
16
+ Creation and reactivation require an unarchived source; existing goals can still
17
+ be paused or archived while their source is archived, as explained below.
18
+ `metricId` cannot change on an existing goal.
19
+
20
+ ```sh
21
+ geniustasker metrics list --scope project:PROJECT --id METRIC_UUID --json
22
+ geniustasker metrics list --scope project:PROJECT --collection metricGoals --json
23
+ geniustasker metrics list --scope personal:OWNER --collection personalMetricGoals --id GOAL_UUID --json
24
+ geniustasker commands describe --kind metric.goal.create --json
25
+ geniustasker workflow show --topic metrics --json
26
+ ```
27
+
28
+ In MCP use `tasker_read_metrics` and `tasker_edit_metrics`. Read one bounded page
29
+ at a time; preserve the returned epoch, checkpoint and continuation. Goal
30
+ collections accept an exact goal `id`; `metricId` filtering is reserved for
31
+ observation/correction history. Do not scan all history to recompute progress.
32
+
33
+ ## Choose the target and period
34
+
35
+ `target` is a decimal **string** in the source metric's unit, with a dot and at
36
+ most its configured precision. No exponent, thousands separator, percentage
37
+ symbol or JSON number. For a Ratio with `ratioScale:100`, target `"75"` means
38
+ 75 percent; for scale 1 use `"0.75"` if the precision supports it. Preserve exact
39
+ decimal arithmetic instead of converting the threshold through floating point.
40
+ `AtLeast` means greater than or equal; `AtMost` means less than or equal.
41
+
42
+ `window:null` uses the recorded lifetime. A fixed window has explicit
43
+ timezone-qualified `start` and `end`, with start **included** and end **excluded**.
44
+ Choose boundaries in the user's intended timezone, then retain those instants.
45
+ It is not a recurring or rolling period. A goal called “This week” does not
46
+ advance itself next week. Date membership uses the observation's `observedAt`,
47
+ including late arrivals, corrections and voids, not its ingestion time.
48
+
49
+ Choose `OnReach` for completion as soon as a complete eligible result satisfies
50
+ the target. Choose `AtEnd` to wait for the fixed window's end; it requires a
51
+ non-null window. An upper-bound budget often needs `AtEnd`, since being below
52
+ the limit early does not establish the final result. Later evidence can still
53
+ correct a window's result after its end.
54
+
55
+ ## Persist explicit configuration
56
+
57
+ This `data` example assumes a EUR Counter/Sum source with precision 2. The UUID
58
+ is illustrative: use the actual definition ID and the agreed dates and target.
59
+ Notification and coach options are off because the example does not request
60
+ either. Titles and explanations may use the user's language; API names and enum
61
+ values stay unchanged.
62
+
63
+ ```json
64
+ {
65
+ "configuration": {
66
+ "metricId": "00000000-0000-4000-8000-000000000001",
67
+ "title": "Budget de novembre",
68
+ "description": "Dépenses vérifiées en euros sur novembre, clôture au terme de la période.",
69
+ "target": "500.00",
70
+ "comparison": "AtMost",
71
+ "window": {
72
+ "start": "2026-11-01T00:00:00+01:00",
73
+ "end": "2026-12-01T00:00:00+01:00"
74
+ },
75
+ "completion": "AtEnd",
76
+ "notifyCompleted": false,
77
+ "coachSignal": false,
78
+ "paused": false,
79
+ "archived": false
80
+ }
81
+ }
82
+ ```
83
+
84
+ Create with a new stable goal UUID, the scope's current epoch and
85
+ `expectedRevision:null`. For update, reread the goal and use its current revision
86
+ with the complete configuration, preserving unchanged choices. `metric.goal.delete`
87
+ takes empty `data` and a current revision; it does not delete the source metric
88
+ or its evidence. Never send the internal action, progress, scan cursor,
89
+ generation, attribution or completion fields.
90
+
91
+ Keep configuration concise: the current service limits it to 2,048 UTF-8 bytes
92
+ and admits at most 12 goals per metric, 128 per scope. These bounds apply in
93
+ addition to individual field limits. A refusal is not a reason to clone the
94
+ metric, split the same goal or rotate an agent profile.
95
+
96
+ Use the normal immutable command journal: prepare, then execute/retry the exact
97
+ operation. A lost acknowledgment is not a reason to create a second goal.
98
+ Revision conflicts require rereading before a new intentional edit. Hosted MCP
99
+ does not retain a local journal, so preserve the prepared request yourself.
100
+ Each read/write uses normal permissions and budgets; no bulk loop is implied.
101
+
102
+ ## Report trustworthy progress
103
+
104
+ - `phase:"Pending"` means historical evaluation is incomplete. A bounded server
105
+ scan may already expose partial summary data; do not present it as the final
106
+ total, failure or success. Do not busy-poll or try to advance `scanAfter` yourself.
107
+ - `phase:"Ready"` means the summary is complete for the recorded evidence.
108
+ Use the server's `reached` result; comparison uses exact unrounded arithmetic.
109
+ `summary.value` is a nullable, rounded display string and can appear equal to
110
+ a threshold that the exact result has not reached. Summary integer fields
111
+ follow the [same scaling rules](metrics-observations.md#read-the-consolidated-result)
112
+ as the source; a goal's summary is restricted to its configured window.
113
+ - No active evidence yields `summary.value:null`, not a measured zero, even for
114
+ an `AtMost` target. Ready does not itself prove recent or complete external
115
+ data: inspect `latest.observedAt` and the definition's freshness configuration.
116
+ - `completedAt` records the first verified eligible completion. It is retained
117
+ through corrections, edits and retries. The current `reached` value can later
118
+ become false without erasing that historical fact. Do not recreate a goal to
119
+ repeat a reward, or confuse a completion record with confirmed push delivery.
120
+
121
+ `paused:true` retains progress tracking while suppressing automatic completion
122
+ reactions. `archived:true` stops tracking; restoration rebuilds progress before
123
+ reacting. Neither option discards evidence or clears prior completion.
124
+
125
+ Archiving the **source metric** also parks its goals’ pending scans and scheduled
126
+ checks without discarding progress. You can pause or archive an existing goal,
127
+ and clarify its title or description while keeping it paused/archived. You
128
+ cannot create a new goal, reactivate an archived goal, or change its target,
129
+ comparison, completion rule or window until the source is restored. A
130
+ `metric_paused` refusal is not a reason to reactivate the source without the
131
+ user’s request.
132
+
133
+ Restoring the source resumes a retained scan cursor or an outstanding `AtEnd`
134
+ boundary. A partial scan cannot complete early, and an `AtEnd` goal waits until
135
+ its boundary. Explicit goal pauses and archives remain in effect; restoration
136
+ does not clear them or reset `completedAt`.
137
+
138
+ `notifyCompleted` and `coachSignal` are explicit opt-ins; leave them false unless
139
+ requested, and preserve existing choices on update. They describe eligibility,
140
+ not evidence that a message was delivered or XP awarded. Recipient preferences
141
+ and the live service still apply. `coachSignal` does not issue an LLM request,
142
+ invoke an external agent, execute code or install a collector. Report saved
143
+ configuration, calculated progress and observed delivery as separate facts.
@@ -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.
@@ -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
package/src/changes.mjs CHANGED
@@ -4,14 +4,11 @@ import { AgentClient } from './client.mjs';
4
4
  import { Transport } from './transport.mjs';
5
5
  import catalog from './command-catalog.mjs';
6
6
  import { fail } from './errors.mjs';
7
+ import { resourceScopeSchema, validateResourceScope } from './resources.mjs';
7
8
 
8
9
  export const changesSchema = z
9
10
  .object({
10
- scope: z
11
- .string()
12
- .max(256)
13
- // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
14
- .regex(/^(project|memory):[^\u0000-\u001f]+$/u),
11
+ scope: resourceScopeSchema,
15
12
  collection: z.string().min(1).max(32),
16
13
  cursor: z.string().min(1).max(4096),
17
14
  })
@@ -59,6 +56,7 @@ function query(input, schema) {
59
56
  'Use a project or memory scope, collection and unchanged change cursor; waitSeconds must be within the supported bound.',
60
57
  );
61
58
  }
59
+ validateResourceScope(parsed.data);
62
60
  return parsed.data;
63
61
  }
64
62
  /** Validate the entire bounded page before a caller can adopt its next cursor. */
package/src/cli.mjs CHANGED
@@ -18,6 +18,7 @@ import { readMemoryTree, readMemoryMarkdown } from './documentation.mjs';
18
18
  import { searchMemory, exploreGraph, resolveMemory } from './knowledge.mjs';
19
19
  import { previewProtocol } from './protocols.mjs';
20
20
  import { reportRunEvent } from './run-events.mjs';
21
+ import { readResources, readMetrics } from './resources.mjs';
21
22
  import { MediaJournal, mediaAction, downloadMedia, compareMedia } from './media.mjs';
22
23
  import { fail, safeError, exitCode } from './errors.mjs';
23
24
  import { checkUpdate, installUpdate, maybeNotifyUpdate } from './update.mjs';
@@ -70,6 +71,11 @@ export const commands = {
70
71
  summary: 'List independent account memories; follow nextAfter even for an empty page.',
71
72
  options: ['after'],
72
73
  },
74
+ 'metrics list': {
75
+ summary:
76
+ 'Read one bounded page of custom metric definitions (default), observations, corrections or linked goals. Select --collection; requires metrics:read.',
77
+ options: ['scope', 'collection', 'id', 'metric-id', 'after', 'epoch', 'checkpoint', 'archive'],
78
+ },
73
79
  'media compare': {
74
80
  summary: 'Compare a local file with an existing resource before uploading a replacement.',
75
81
  options: ['scope', 'id', 'file'],
@@ -138,7 +144,17 @@ export const commands = {
138
144
  },
139
145
  'resources list': {
140
146
  summary: 'Read a project or memory collection; carry epoch/checkpoint when continuing.',
141
- options: ['scope', 'collection', 'after', 'epoch', 'checkpoint', 'archive', 'id', 'path'],
147
+ options: [
148
+ 'scope',
149
+ 'collection',
150
+ 'after',
151
+ 'epoch',
152
+ 'checkpoint',
153
+ 'archive',
154
+ 'id',
155
+ 'path',
156
+ 'metric-id',
157
+ ],
142
158
  },
143
159
  'changes list': {
144
160
  summary:
@@ -515,28 +531,41 @@ export async function main(
515
531
  ...(input.block === undefined ? {} : { blockId: input.block }),
516
532
  });
517
533
  }
534
+ } else if (command === 'metrics list') {
535
+ const input = Object.fromEntries(
536
+ commands[command].options
537
+ .filter((key) => options[key] !== undefined)
538
+ .map((key) => [key === 'metric-id' ? 'metricId' : key, options[key]]),
539
+ );
540
+ data = await readMetrics(client, {
541
+ ...input,
542
+ collection:
543
+ options.collection ??
544
+ (options.scope?.startsWith('personal:') ? 'personalMetrics' : 'metrics'),
545
+ });
518
546
  } else if (command === 'resources list' || command === 'questions answers') {
519
547
  if (
520
548
  !(command === 'questions answers'
521
549
  ? options.scope?.startsWith('project:')
522
550
  : // eslint-disable-next-line no-control-regex -- Reject control characters in untrusted input.
523
- /^(project|memory):[^\u0000-\u001f]+$/.test(options.scope ?? '')) ||
551
+ /^(project|memory|personal):[^\u0000-\u001f]+$/.test(options.scope ?? '')) ||
524
552
  !(command === 'resources list' ? options.collection : options.question) ||
525
553
  (options.after && (!options.epoch || !options.checkpoint))
526
554
  ) {
527
555
  fail(
528
556
  'invalid_arguments',
529
- 'Use --scope project:ID or memory:ID and --collection for resources or --question for answers; continuation needs --epoch and --checkpoint.',
557
+ 'Use --scope project:ID or memory:ID and --collection for resources or --question for answers; personal:<connected-owner> is limited to metric definitions, observations and corrections. Continuation needs --epoch and --checkpoint.',
530
558
  );
531
559
  }
532
- data = await client.get(
533
- command === 'resources list' ? 'resources' : 'answers',
534
- Object.fromEntries(
535
- commands[command].options
536
- .filter((key) => options[key] !== undefined)
537
- .map((key) => [key, options[key]]),
538
- ),
560
+ const input = Object.fromEntries(
561
+ commands[command].options
562
+ .filter((key) => options[key] !== undefined)
563
+ .map((key) => [key === 'metric-id' ? 'metricId' : key, options[key]]),
539
564
  );
565
+ data =
566
+ command === 'resources list'
567
+ ? await readResources(client, input)
568
+ : await client.get('answers', input);
540
569
  } else if (command === 'mcp') {
541
570
  const { runMcp } = await import('./mcp.mjs');
542
571
  const server = await runMcp(client);