{"id":"75a15ddc-a392-464d-a66e-b3203729808c","entityType":"agent","slug":"clawhub-arc-claw-bot-fulcra-annotations","name":"Fulcra Annotations","canonicalUrl":"https://www.xpersona.co/agent/clawhub-arc-claw-bot-fulcra-annotations","canonicalPath":"/agent/clawhub-arc-claw-bot-fulcra-annotations","generatedAt":"2026-10-10T06:43:48.235Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":null},"description":"Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/defin...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s177v15fjt9pn5v99vms8sqkfn86vdwr:fulcra-annotations","sourceUrl":"https://clawhub.ai/arc-claw-bot/fulcra-annotations","homepage":"https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/arc-claw-bot/fulcra-annotations","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":67,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Fulcra Annotations technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":null},"stars":null,"forks":null,"downloads":2219,"packageName":null,"latestVersion":"1.0.16","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:05.083Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:26:05.113Z","lastCrawledAt":"2026-10-09T17:26:05.083Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:26:05.083Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.16","createdAt":"2026-07-12T11:11:07.166Z","changelog":"Refresh fulcra-api 0.1.36 wording while restoring the clean legacy helper surface with inline readback verification.","fileCount":7,"zipByteSize":16098},{"version":"1.0.15","createdAt":"2026-07-12T11:03:46.163Z","changelog":"Refresh fulcra-api 0.1.36 wording and narrow the bundled helper surface by removing env token/API/command overrides and destructive delete support.","fileCount":7,"zipByteSize":18580},{"version":"1.0.14","createdAt":"2026-07-09T18:39:18.586Z","changelog":"Document typed ingest and versioned catalog/schema OpenAPI surfaces while preserving readback verification rules.","fileCount":7,"zipByteSize":17285},{"version":"1.0.13","createdAt":"2026-07-02T15:29:15.753Z","changelog":"Harden annotation helper scan posture with API-host allowlisting, trusted CLI command validation, explicit permissions, and narrower routing.","fileCount":7,"zipByteSize":16286},{"version":"1.0.12","createdAt":"2026-07-02T15:19:38.605Z","changelog":"Clarify that data-updates is a coarse diagnostic, not annotation record write verification.","fileCount":7,"zipByteSize":15682},{"version":"1.0.11","createdAt":"2026-05-29T16:06:44.784Z","changelog":"Restore Fulcra Annotations display name after scan-clean auth update.","fileCount":7,"zipByteSize":15407},{"version":"1.0.10","createdAt":"2026-05-29T16:06:02.903Z","changelog":"Clean public auth helper naming and scanner-sensitive defaults while preserving CLI-first Fulcra annotation writes.","fileCount":7,"zipByteSize":15345},{"version":"1.0.9","createdAt":"2026-05-29T10:54:55.773Z","changelog":"Update Fulcra account/auth guidance: CLI account creation, 5 GB free storage, remote device link/code handoff, and app subscription status.","fileCount":7,"zipByteSize":16081}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s177v15fjt9pn5v99vms8sqkfn86vdwr:fulcra-annotations","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s177v15fjt9pn5v99vms8sqkfn86vdwr:fulcra-annotations` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/arc-claw-bot/fulcra-annotations before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:43:48.233Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-arc-claw-bot-fulcra-annotations/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":null},"readme":"Skill: Fulcra Annotations\n\nOwner: arc-claw-bot\n\nSummary: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/defin...\n\nTags: latest:1.0.16\n\nVersion history:\n\nv1.0.16 | 2026-07-12T11:11:07.166Z | user\n\nRefresh fulcra-api 0.1.36 wording while restoring the clean legacy helper surface with inline readback verification.\n\nv1.0.15 | 2026-07-12T11:03:46.163Z | user\n\nRefresh fulcra-api 0.1.36 wording and narrow the bundled helper surface by removing env token/API/command overrides and destructive delete support.\n\nv1.0.14 | 2026-07-09T18:39:18.586Z | user\n\nDocument typed ingest and versioned catalog/schema OpenAPI surfaces while preserving readback verification rules.\n\nv1.0.13 | 2026-07-02T15:29:15.753Z | user\n\nHarden annotation helper scan posture with API-host allowlisting, trusted CLI command validation, explicit permissions, and narrower routing.\n\nv1.0.12 | 2026-07-02T15:19:38.605Z | user\n\nClarify that data-updates is a coarse diagnostic, not annotation record write verification.\n\nv1.0.11 | 2026-05-29T16:06:44.784Z | user\n\nRestore Fulcra Annotations display name after scan-clean auth update.\n\nv1.0.10 | 2026-05-29T16:06:02.903Z | user\n\nClean public auth helper naming and scanner-sensitive defaults while preserving CLI-first Fulcra annotation writes.\n\nv1.0.9 | 2026-05-29T10:54:55.773Z | user\n\nUpdate Fulcra account/auth guidance: CLI account creation, 5 GB free storage, remote device link/code handoff, and app subscription status.\n\nv1.0.8 | 2026-05-28T14:09:20.325Z | user\n\nAdd publisher note explaining Fulcra annotation API access for ClawScan.\n\nv1.0.7 | 2026-05-27T22:34:01.467Z | user\n\nRemove location-specific wording from the public timezone example after post-upload review.\n\nv1.0.6 | 2026-05-27T22:31:55.523Z | user\n\nRefresh published skill with local privacy, CLI, and schema-inspection fixes.\n\nv1.0.5 | 2026-05-26T20:08:48.068Z | user\n\nAdd definition update/delete commands, document ledger-backed idempotent annotation writers, clarify filterable tag design, and strengthen readback verification semantics.\n\nv1.0.4 | 2026-05-21T15:58:39.504Z | user\n\nUpdate Fulcra CLI auth default to uv tool run fulcra-api and preserve uv cache paths when FULCRA_HOME points at alternate credentials.\n\nv1.0.3 | 2026-05-21T01:55:11.747Z | user\n\nReference companion fulcra-context skill, document closed-loop read/write workflows, improve remote auth guidance, and restore beta Fulcra CLI fallback for hosts without a fulcra-api binary.\n\nv1.0.2 | 2026-05-16T19:33:09.813Z | user\n\nMake remote auth guidance channel-agnostic\n\nv1.0.1 | 2026-05-16T19:28:27.497Z | user\n\nDocument remote device-code auth for chat-based agents\n\nv1.0.0 | 2026-05-16T15:01:52.795Z | user\n\nInitial ClawHub release: create and record Fulcra annotations with tags, historical timestamps, and readback verification\n\nArchive index:\n\nArchive v1.0.16: 7 files, 16098 bytes\n\nFiles: agents/openai.yaml (186b), README.md (5944b), references/api-notes.md (1589b), scripts/fulcra_annotations.py (16507b), skill-card.md (2418b), SKILL.md (16080b), _meta.json (138b)\n\nFile v1.0.16:SKILL.md\n\n---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"uv\"]},\"permissions\":[\"shell:uv-tool-run-fulcra-api\",\"network:https://api.fulcradynamics.com\",\"env:FULCRA_ACCESS_TOKEN\",\"env:FULCRA_HOME\",\"env:FULCRA_AGENT_SOURCE\"]}}\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the bundled script first. Do not hand-write curl calls unless the script is missing a required capability, because the script keeps tokens out of chat, builds the Fulcra ingest payload consistently, and performs readback verification.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` or `Asked Agent to Do Something New`. Created once with `create`.\n- **Annotation record**: one logged occurrence/value of a definition. Written with `record`.\n- **Moment annotation**: an event with no value. Use for \"this happened\" logs.\n- **Boolean/numeric/scale annotations**: metric-like records that require `--value`.\n- **Definition tags**: reusable labels stored on the annotation definition. Add them when creating the definition with repeated `create --tag`.\n- **Record tags**: labels stored on one specific record. Add them when recording with repeated `record --tag`.\n- **Tag resolution**: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and creates missing tag names automatically.\n- **Historical record**: any record whose event time is not now. Always pass `--recorded-at`.\n- **Confirmed write**: a record is not confirmed until readback finds `verified_matches >= 1`.\n\n## Safety Rules\n\n- Never print access tokens, refresh tokens, raw private Fulcra records, credential files, or direct capability URLs in chat.\n- Authenticated API calls are pinned to `https://api.fulcradynamics.com`; do not redirect Fulcra bearer tokens to custom API hosts.\n- `FULCRA_CLI_COMMAND` is restricted to the standard Fulcra CLI invocation (`uv tool run fulcra-api`, `fulcra-api`, or a trusted absolute path ending in `fulcra-api`).\n- Device auth URLs and user codes are allowed only when the intended user needs to approve Fulcra access from another device; send them only through the active trusted user channel.\n- Ask before deleting or updating an existing annotation definition.\n- For public demos, use synthetic annotation names/values unless the user explicitly approves real data.\n- Do not claim a write succeeded from HTTP status alone. Check the script result and verify readback.\n- Duration annotations are only partially supported by this skill; prefer moment/boolean/numeric/scale until Fulcra documents duration ingest shape more clearly.\n\n## Auth\n\nThe script gets auth from a trusted secret manager token when `FULCRA_ACCESS_TOKEN` is set, otherwise from the locally authenticated Fulcra CLI command configured by `FULCRA_CLI_COMMAND`.\n\nFulcra requires an authenticated account, not an API key. Accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nAuthenticate first:\n\n```bash\nuv tool run fulcra-api auth login\n```\n\nFor remote agents, keep the CLI running, surface the printed device authorization URL and code to the intended user in chat through the active trusted user channel, and wait for approval. The user can open the URL from any browser on any device. After approval, verify auth with a non-token command such as `uv tool run fulcra-api user-info`; do not paste tokens into chat.\n\nSet `FULCRA_HOME=/path/to/home` if credentials are not under the process `HOME`.\n\n## Common Commands\n\nList annotation definitions before creating a new one:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nUse `create --tag` more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as `agent`, `health`, or `research`. The script resolves tag names to Fulcra tag IDs before sending the API payload.\n\nRecord a moment annotation now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nUse `record --tag` more than once to attach tags to the individual record. If `record --tag` is omitted, the record inherits the definition tags. If `record --tag` is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.\n\nRecord a historical moment annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\"\n```\n\nUse a full ISO-8601 timestamp with timezone for historical writes. If the user says \"yesterday at 10am\", resolve it in the user's timezone and pass the offset explicitly, for example `2026-05-15T10:00:00-04:00`. Fulcra readback may show the equivalent UTC time, such as `2026-05-15T14:00:00+00:00`.\n\nRecord by annotation ID when names are ambiguous:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\"\n```\n\nCreate a 1-5 scale annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type scale \\\n --name \"Focus\" \\\n --description \"How focused do I feel right now?\" \\\n --scale-labels \"1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In\" \\\n --default-value 3\n```\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor measurements with specialized units, inspect the live Fulcra schema through the official CLI or library before creating the definition and then prefer adding reviewed helper support over ad hoc API calls.\n\nRecord a scale/numeric/boolean value:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" \\\n --value 4 \\\n --note \"Deep work block started well\"\n```\n\nRead back recent records for verification:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent \\\n --name \"Asked Agent to Do Something New\" \\\n --hours 72 \\\n --limit 20\n```\n\nUpdate or delete definition metadata only through a separate reviewed admin workflow after explicit user approval. The bundled helper intentionally exposes only `list`, `create`, `record`, and `recent`.\n\nDry-run any write before sending it:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" --value 4 --dry-run\n```\n\n## Workflow\n\n1. Determine the annotation type: moment, boolean, numeric, or scale. Prefer moment for \"this happened\".\n2. Decide whether tags belong on the definition, the individual record, or both.\n3. Run `list` and check whether the definition already exists.\n4. If an existing definition needs a metadata or tag change, ask for approval and use `update --id ...`; dry-run first for broad retagging.\n5. If the definition is missing and the user asked to create/log that annotation, run `create`.\n6. Record with `record --name ...` or `record --id ...`.\n7. For historical writes, always include `--recorded-at \"\"`.\n8. Trust only a successful script result with `verified_matches >= 1` for confirmed writes.\n9. If verification fails after ingest returns `204`, wait briefly and rerun `recent --id ` or `recent --name \"\" --hours `.\n10. Report the exact timestamp written and the readback timestamp. Do not include tokens, direct capability URLs, or unnecessary private record data.\n\n## Demo and Handoff Pattern\n\nFor onboarding, the first verified record should lead to a small payoff instead of a dry \"done\" message.\n\n- Offer 2-3 visual directions and ask the user to choose before generating a dashboard or artifact.\n- Keep demo files local to the workspace and avoid dumping raw HTML or raw Fulcra records into chat.\n- Use the verified annotation name, timestamp, value, and a short interpretation. Avoid exposing unrelated Fulcra data.\n- Make the next steps concrete: install/open the Context app for mobile logging, inspect data in Context Web, add another annotation, or iterate on the dashboard.\n- In public or group-chat demos, use synthetic values unless the user explicitly approved sharing real values.\n\n## Idempotent Writer Pattern\n\nFor automated or backfilled annotation pipelines, use an append-only, ledger-backed writer:\n\n1. Normalize the source event into stable fields: annotation name/id, event timestamp, source, severity/category, value/note, and any real filter dimensions.\n2. Generate a dedupe key from stable source facts. Keep this key in local state, metadata, or source bookkeeping; do not place it in the visible note.\n3. Check the local ledger before writing. Skip `verified`, retry `pending` or `failed`, and write only unseen keys.\n4. Treat ingest HTTP success as provisional. Confirm with `record` output or `recent` readback and mark the ledger `verified` only when `verified_matches >= 1`.\n5. For changed source events, avoid duplicate annotations unless the change is materially new. Prefer a follow-up annotation for escalation/resolution over rewriting history.\n\n## Tag Rules\n\n- Use definition tags for stable classification of the annotation itself, such as `health`, `agent`, `research`, or `workflow`.\n- Use record tags for context that applies only to one logged occurrence, such as `new-task`, `manual-test`, `backfill`, or `user-requested`.\n- Add definition tags with `create --tag `. Repeat `--tag` for multiple definition tags.\n- Add record tags with `record --tag `. Repeat `--tag` for multiple record tags.\n- `--tag` accepts either a Fulcra tag name or an existing tag UUID.\n- Fulcra stores tags as UUIDs. The script resolves tag names to UUIDs and creates a missing tag name automatically.\n- If `record --tag` is omitted, the record uses the definition tags.\n- If `record --tag` is provided, the explicit record tags are sent for that record.\n- Use lowercase, short, reusable tags. Prefer `new-task` over a full sentence.\n- Tags should be filter dimensions, not prose. For places, prefer actual geography such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus` over abstract tags such as `scope-town` or `scope-neighborhood`.\n- Pair place tags with category/source/severity tags when useful, for example `category-traffic`, `source-town-feed`, or `severity-advisory`.\n- Do not use tags for timestamps, detailed notes, values, people names, dedupe keys, or private context. Use `--recorded-at`, `--note`, `--value`, `--source`, and local metadata/ledger state for those.\n- Existing definitions can be retagged with `update --id ... --tag ...` after user approval; `--tag` replaces the definition tag set.\n\n## Timestamp Rules\n\n- If `--recorded-at` is omitted, the script records the annotation at the current time.\n- If the user asks for a historical or scheduled-looking time, pass `--recorded-at`.\n- Use the user's local timezone when resolving relative phrases like \"yesterday at 10am\".\n- Include the timezone offset in the timestamp. Do not pass naive local times.\n- UTC readback is expected. Compare instants, not string equality.\n\nExample: on 2026-05-16 in Eastern Time, \"yesterday at 10am\" means `2026-05-15T10:00:00-04:00`, which readback may show as `2026-05-15T14:00:00+00:00`.\n\n## Verification Rules\n\n- `record` returns `recorded_at` and `verified_matches`.\n- `verified_matches >= 1` means the script found the written record in Fulcra after ingest.\n- `uv tool run fulcra-api data-updates ` can show that annotation-related data types were processed in a time range, but it is not record-level write verification. Do not use update counts as proof that a specific annotation record was created, changed, or deleted.\n- For historical writes, use `recent --hours` with a window large enough to include the target time if a second verification is needed.\n- When inspecting readback, use only minimal fields needed for confirmation: annotation name/id, `recorded_at`, value if relevant, and note if relevant.\n\n## API Notes\n\nCore REST endpoints:\n\n- `GET /user/v1alpha1/annotation` lists annotation definitions.\n- `POST /user/v1alpha1/annotation` creates a definition.\n- `PUT /user/v1alpha1/annotation/{annotation_id}` updates a definition.\n- `DELETE /user/v1alpha1/annotation/{annotation_id}` deletes a definition.\n- `POST /ingest/v1/record` records annotation events.\n- `POST /ingest/v1/record/batch` records batches of annotation events.\n- Readback uses `/data/v1alpha1/event/MomentAnnotation` for moment/duration and `/data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation}` for metric annotation values.\n\nFor bulk or backfill pipelines, `data-updates` is a coarse freshness diagnostic after ingest. It supplements the local ledger and record readback; it does not replace either.\n\nFor schema details or upstream gaps, read `references/api-notes.md`.\n\nFile v1.0.16:README.md\n\n# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates, updates, and deletes annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed, or `FULCRA_ACCESS_TOKEN` supplied by a trusted secret manager.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. Set `FULCRA_CLI_COMMAND` only when you need to override the default `uv tool run fulcra-api` command.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at least `1`.\n\n## First-Run Flow\n\nFor a new user, keep the first annotation loop tight:\n\n1. Offer 2-3 concrete tracking ideas instead of asking an open-ended question.\n2. Check auth with `uv tool run fulcra-api user-info`; if needed, run `uv tool run fulcra-api auth login` and send only the device URL/code.\n3. Create 1-3 definitions, saving the returned `annotation.id`, `source_id`, and type in your working notes.\n4. Ask one direct question, record the first value with `record --id ...`, and verify `verified_matches >= 1`.\n5. Hand off with the definitions created, the timestamp written, and a concrete next step such as mobile logging, Context Web, another annotation, or a small dashboard.\n\nFor public demos or group chats, use synthetic values unless the user explicitly approves sharing real Fulcra records.\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor specialized measurement units, inspect the live Fulcra schema through the official CLI or library before adding reviewed helper support.\n\nUpdate or delete definitions only through a separate reviewed admin workflow after explicit user approval. The bundled helper intentionally exposes only `list`, `create`, `record`, and `recent`.\n\n## Idempotent Pipelines\n\nFor recurring imports or backfills, keep a local ledger keyed by stable source facts. Write unseen records once, retry pending/failed records, and mark a record verified only after Fulcra readback. Keep dedupe keys out of visible notes; store them in local state, metadata, or source bookkeeping.\n\n## Tags\n\nTags can apply to either the definition or an individual record.\n\nUse definition tags for stable categories that describe the annotation itself:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Medication Taken\" \\\n --tag health \\\n --tag adherence\n```\n\nUse record tags for context that only applies to one event:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Medication Taken\" \\\n --note \"Backfilled after travel\" \\\n --tag backfill \\\n --tag travel\n```\n\nUse short, reusable, lowercase tags such as `health`, `agent`, `research`, `new-task`, `manual-test`, or `backfill`. Tags should be filter dimensions. For geography, prefer actual place tags such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus`, not abstract scope labels. Do not put timestamps, private notes, dedupe keys, or one-off sentences in tags.\n\n## Safety\n\n- Do not print access tokens, direct capability URLs, or private Fulcra records in chat or logs.\n- Use dry-run mode before risky writes.\n- Ask before deleting or changing an existing annotation definition.\n\nFile v1.0.16:_meta.json\n\n{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.16\",\n \"publishedAt\": 1783854667166\n}\n\nFile v1.0.16:references/api-notes.md\n\n# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n- `DELETE /user/v1alpha1/annotation/{annotation_id}`\n- `POST /user/v1alpha1/annotation/{annotation_id}/cancel_deletion`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe generic ingest endpoint is:\n\n`POST /ingest/v1/record`\n\nPayload shape:\n\n```json\n{\n \"specversion\": 1,\n \"data\": \"{\\\"note\\\":\\\"optional note\\\",\\\"value\\\":4}\",\n \"metadata\": {\n \"data_type\": \"ScaleAnnotation\",\n \"recorded_at\": \"2026-05-14T19:30:00Z\",\n \"source\": [\n \"com.example.agent\",\n \"com.fulcradynamics.annotation.\"\n ],\n \"tags\": [],\n \"content_type\": \"application/json\"\n }\n}\n```\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Current Gaps\n\nThe beta CLI currently does not expose annotation write commands or Magic Link retrieval. Prefer the bundled REST script until upstream CLI support lands.\n\nFile v1.0.16:skill-card.md\n\n## Description:\n\nCreate, list, record, and verify Fulcra annotation definitions and events through the Fulcra Life API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to create Fulcra annotation definitions, record approved moment or metric annotations, and verify writes through readback.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Authentication depends on local Fulcra CLI execution and account credentials.\n\nMitigation: Install only with a trusted Fulcra account, API endpoint, and CLI supply chain; prefer a pinned reviewed CLI version or vetted local binary.\n\nRisk: Broad FULCRA_CLI_COMMAND overrides could route authentication through an unintended executable.\n\nMitigation: Keep the default Fulcra CLI invocation when possible and avoid overrides unless the executable path has been reviewed.\n\nRisk: Update, delete, bulk, or backfill workflows can change existing annotation state or create many records.\n\nMitigation: Require explicit user confirmation, use dry-run mode before writes, and use a reviewed admin or ledger-backed workflow for broad changes.\n\nRisk: Fulcra records and tokens may contain private user data.\n\nMitigation: Do not print access tokens, credential files, capability URLs, or raw private records in chat or logs; share device authorization details only through the trusted user channel.\n\n## Reference(s):\n\n- [Fulcra Annotation API Notes](references/api-notes.md)\n- [Fulcra API OpenAPI document](https://api.fulcradynamics.com/openapi.json)\n- [ClawHub skill page](https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, JSON]\n\n**Output Format:** [Markdown guidance with bash commands and JSON command results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Fulcra authentication and readback verification for confirmed writes.]\n\n## Skill Version(s):\n\n1.0.16 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.16:agents/openai.yaml\n\ninterface:\n display_name: \"Fulcra Annotations\"\n short_description: \"Create, list, and record Fulcra annotations from agents.\"\n default_prompt: \"Create or record a Fulcra annotation.\"\n\nArchive v1.0.15: 7 files, 18580 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6472b), references/api-notes.md (4446b), scripts/fulcra_annotations.py (19377b), skill-card.md (2467b), SKILL.md (17218b), _meta.json (138b)\n\nFile v1.0.15:SKILL.md\n\n---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the highest-level supported surface for each operation:\n\n- For annotation definitions and tags, prefer `uv tool run fulcra-api data-type ...` and `uv tool run fulcra-api tag ...`, or the equivalent `fulcra_api` Python helpers, when shell/Python is available.\n- For annotation timeline records, use the bundled script or an ingest-backed helper with readback verification. Fulcra CLI 0.1.36 still does not expose record write/delete/replace commands.\n- Do not hand-write curl calls unless the CLI/lib and bundled script are both missing the required capability.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` or `Asked Agent to Do Something New`. Created once with `create`.\n- **Annotation record**: one logged occurrence/value of a definition. Written with `record`.\n- **Moment annotation**: an event with no value. Use for \"this happened\" logs.\n- **Boolean/numeric/scale annotations**: metric-like records that require `--value`.\n- **Definition tags**: reusable labels stored on the annotation definition. Add them when creating the definition with repeated `create --tag`.\n- **Record tags**: labels stored on one specific record. Add them when recording with repeated `record --tag`.\n- **Tag resolution**: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and creates missing tag names automatically.\n- **Historical record**: any record whose event time is not now. Always pass `--recorded-at`.\n- **Confirmed write**: a record is not confirmed until readback finds `verified_matches >= 1`.\n\n## Safety Rules\n\n- Never print access tokens, refresh tokens, raw private Fulcra records, credential files, or direct capability URLs in chat.\n- Device auth URLs and user codes are allowed only when the intended user needs to approve Fulcra access from another device; send them only through the active trusted user channel.\n- Ask before updating an existing annotation definition.\n- The bundled helper does not expose destructive definition deletes; use a separate reviewed admin workflow for deletion.\n- For public demos, use synthetic annotation names/values unless the user explicitly approves real data.\n- Do not claim a write succeeded from HTTP status alone. Check the script result and verify readback.\n- Duration annotations are only partially supported by this skill; prefer moment/boolean/numeric/scale until Fulcra documents duration ingest shape more clearly.\n\n## Auth\n\nThe script gets auth from the locally authenticated Fulcra CLI by running `uv tool run fulcra-api auth print-access-token`. It does not accept access tokens, API base overrides, or CLI command overrides from chat or environment variables.\n\nFulcra requires an authenticated account, not an API key. Accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nAuthenticate first:\n\n```bash\nuv tool run fulcra-api auth login\n```\n\nFor remote agents, keep the CLI running, surface the printed device authorization URL and code to the intended user in chat through the active trusted user channel, and wait for approval. The user can open the URL from any browser on any device. After approval, verify auth with a non-token command such as `uv tool run fulcra-api user-info`; do not paste tokens into chat.\n\nSet `FULCRA_HOME=/path/to/home` only if credentials are not under the process `HOME`.\n\n## Common Commands\n\nList annotation definitions before creating a new one:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCheck first-class definition and tag surfaces:\n\n```bash\nuv tool run fulcra-api data-type --help\nuv tool run fulcra-api tag --help\nuv tool run fulcra-api catalog --base-types-only\n```\n\nUse live help for exact type names and options before creating definitions with `data-type create`.\n\nCreate a moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nUse `create --tag` more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as `agent`, `health`, or `research`. The script resolves tag names to Fulcra tag IDs before sending the API payload.\n\nRecord a moment annotation now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nUse `record --tag` more than once to attach tags to the individual record. If `record --tag` is omitted, the record inherits the definition tags. If `record --tag` is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.\n\nRecord a historical moment annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\"\n```\n\nUse a full ISO-8601 timestamp with timezone for historical writes. If the user says \"yesterday at 10am\", resolve it in the user's timezone and pass the offset explicitly, for example `2026-05-15T10:00:00-04:00`. Fulcra readback may show the equivalent UTC time, such as `2026-05-15T14:00:00+00:00`.\n\nRecord by annotation ID when names are ambiguous:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\"\n```\n\nCreate a 1-5 scale annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type scale \\\n --name \"Focus\" \\\n --description \"How focused do I feel right now?\" \\\n --scale-labels \"1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In\" \\\n --default-value 3\n```\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor measurements with specialized units, inspect the live schema through the bundled helper before creating the definition and then prefer adding script support over ad hoc API calls:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw schema output into chat if it includes private account context.\n\nRecord a scale/numeric/boolean value:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" \\\n --value 4 \\\n --note \"Deep work block started well\"\n```\n\nRead back recent records for verification:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent \\\n --name \"Asked Agent to Do Something New\" \\\n --hours 72 \\\n --limit 20\n```\n\nUpdate definition metadata or replace definition tags only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag workflow \\\n --tag agent\n```\n\nDry-run any write before sending it:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" --value 4 --dry-run\n```\n\n## Workflow\n\n1. Determine the annotation type: moment, boolean, numeric, or scale. Prefer moment for \"this happened\".\n2. Decide whether tags belong on the definition, the individual record, or both.\n3. Run `list` and check whether the definition already exists.\n4. If an existing definition needs a metadata or tag change, ask for approval and use `update --id ...`; dry-run first for broad retagging.\n5. If the definition is missing and the user asked to create/log that annotation, run `create`.\n6. Record with `record --name ...` or `record --id ...`.\n7. For historical writes, always include `--recorded-at \"\"`.\n8. Trust only a successful script result with `verified_matches >= 1` for confirmed writes.\n9. If verification fails after ingest returns `204`, wait briefly and rerun `recent --id ` or `recent --name \"\" --hours `.\n10. Report the exact timestamp written and the readback timestamp. Do not include tokens, direct capability URLs, or unnecessary private record data.\n\n## Demo and Handoff Pattern\n\nFor onboarding, the first verified record should lead to a small payoff instead of a dry \"done\" message.\n\n- Offer 2-3 visual directions and ask the user to choose before generating a dashboard or artifact.\n- Keep demo files local to the workspace and avoid dumping raw HTML or raw Fulcra records into chat.\n- Use the verified annotation name, timestamp, value, and a short interpretation. Avoid exposing unrelated Fulcra data.\n- Make the next steps concrete: install/open the Context app for mobile logging, inspect data in Context Web, add another annotation, or iterate on the dashboard.\n- In public or group-chat demos, use synthetic values unless the user explicitly approved sharing real values.\n\n## Idempotent Writer Pattern\n\nFor automated or backfilled annotation pipelines, use an append-only, ledger-backed writer:\n\n1. Normalize the source event into stable fields: annotation name/id, event timestamp, source, severity/category, value/note, and any real filter dimensions.\n2. Generate a dedupe key from stable source facts. Keep this key in local state, metadata, or source bookkeeping; do not place it in the visible note.\n3. Check the local ledger before writing. Skip `verified`, retry `pending` or `failed`, and write only unseen keys.\n4. Treat ingest HTTP success as provisional. Confirm with `record` output or `recent` readback and mark the ledger `verified` only when `verified_matches >= 1`.\n5. For changed source events, avoid duplicate annotations unless the change is materially new. Prefer a follow-up annotation for escalation/resolution over rewriting history.\n\n## Tag Rules\n\n- Use definition tags for stable classification of the annotation itself, such as `health`, `agent`, `research`, or `workflow`.\n- Use record tags for context that applies only to one logged occurrence, such as `new-task`, `manual-test`, `backfill`, or `user-requested`.\n- Add definition tags with `create --tag `. Repeat `--tag` for multiple definition tags.\n- Add record tags with `record --tag `. Repeat `--tag` for multiple record tags.\n- `--tag` accepts either a Fulcra tag name or an existing tag UUID.\n- Fulcra stores tags as UUIDs. The script resolves tag names to UUIDs and creates a missing tag name automatically.\n- If `record --tag` is omitted, the record uses the definition tags.\n- If `record --tag` is provided, the explicit record tags are sent for that record.\n- Use lowercase, short, reusable tags. Prefer `new-task` over a full sentence.\n- Tags should be filter dimensions, not prose. For places, prefer actual geography such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus` over abstract tags such as `scope-town` or `scope-neighborhood`.\n- Pair place tags with category/source/severity tags when useful, for example `category-traffic`, `source-town-feed`, or `severity-advisory`.\n- Do not use tags for timestamps, detailed notes, values, people names, dedupe keys, or private context. Use `--recorded-at`, `--note`, `--value`, `--source`, and local metadata/ledger state for those.\n- Existing definitions can be retagged with `update --id ... --tag ...` after user approval; `--tag` replaces the definition tag set.\n\n## Timestamp Rules\n\n- If `--recorded-at` is omitted, the script records the annotation at the current time.\n- If the user asks for a historical or scheduled-looking time, pass `--recorded-at`.\n- Use the user's local timezone when resolving relative phrases like \"yesterday at 10am\".\n- Include the timezone offset in the timestamp. Do not pass naive local times.\n- UTC readback is expected. Compare instants, not string equality.\n\nExample: on 2026-05-16 in Eastern Time, \"yesterday at 10am\" means `2026-05-15T10:00:00-04:00`, which readback may show as `2026-05-15T14:00:00+00:00`.\n\n## Verification Rules\n\n- `record` returns `recorded_at` and `verified_matches`.\n- `verified_matches >= 1` means the script found the written record in Fulcra after ingest.\n- For historical writes, use `recent --hours` with a window large enough to include the target time if a second verification is needed.\n- When inspecting readback, use only minimal fields needed for confirmation: annotation name/id, `recorded_at`, value if relevant, and note if relevant.\n\n## API Notes\n\nCore REST endpoints:\n\n- `GET /user/v1alpha1/annotation` lists annotation definitions.\n- `POST /user/v1alpha1/annotation` creates a definition.\n- `PUT /user/v1alpha1/annotation/{annotation_id}` updates a definition.\n- `POST /ingest/v1/record/{data_type}` is the **preferred** typed ingest path (unwrapped record body, closed served-set schema, returns 201 → `{upload_id}`). The helper uses it. See `references/api-notes.md` for per-type served sets and the async/dedup gotchas.\n- `POST /ingest/v1/record` (DataRecordV1 envelope, returns 204) is the legacy path — still published but retirement-eligible; prefer the typed path.\n- `POST /ingest/v1/record/batch` records batches (legacy); the typed path's `application/x-jsonl` mode is preferred for new code.\n- Readback uses `/data/v1alpha1/event/MomentAnnotation` for moment/duration and `/data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation}` for metric annotation values.\n\nFulcra CLI 0.1.36 exposes annotation definition and tag management through `data-type` and `tag` command groups. Prefer those or the Python lib for definitions/tags when available. Timeline record write/delete/replace commands are still absent, so records remain ingest-backed and must be verified with readback.\n\nBefore building a new annotation data type or a typed-ingest helper, inspect the live OpenAPI catalog/schema endpoints:\n\n```text\nGET /data/v1/catalog/{data_type}/{api_version}\nGET /data/v1/catalog/{data_type}/{api_version}/schema\n```\n\nDo not infer payload shape from examples alone. Treat OpenAPI/main drift as a watch signal until the released CLI/lib or a direct schema check confirms the shape.\n\nFor schema details or upstream gaps, read `references/api-notes.md`.\n\nFile v1.0.15:README.md\n\n# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates and updates annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. The bundled helper uses the fixed `uv tool run fulcra-api` command and the canonical Fulcra API base.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nFor definition and tag management, prefer the current Fulcra CLI/lib surfaces when available:\n\n```bash\nuv tool run fulcra-api data-type --help\nuv tool run fulcra-api tag --help\n```\n\nTimeline record writes still use ingest-backed helpers and must be verified with readback.\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at least `1`.\n\n## First-Run Flow\n\nFor a new user, keep the first annotation loop tight:\n\n1. Offer 2-3 concrete tracking ideas instead of asking an open-ended question.\n2. Check auth with `uv tool run fulcra-api user-info`; if needed, run `uv tool run fulcra-api auth login` and send only the device URL/code.\n3. Create 1-3 definitions, saving the returned `annotation.id`, `source_id`, and type in your working notes.\n4. Ask one direct question, record the first value with `record --id ...`, and verify `verified_matches >= 1`.\n5. Hand off with the definitions created, the timestamp written, and a concrete next step such as mobile logging, Context Web, another annotation, or a small dashboard.\n\nFor public demos or group chats, use synthetic values unless the user explicitly approves sharing real Fulcra records.\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor specialized measurement units, inspect the live schema through the bundled helper before adding script support:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw private account output into chat.\n\nUpdate definitions only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag health \\\n --tag workflow\n```\n\n## Idempotent Pipelines\n\nFor recurring imports or backfills, keep a local ledger keyed by stable source facts. Write unseen records once, retry pending/failed records, and mark a record verified only after Fulcra readback. Keep dedupe keys out of visible notes; store them in local state, metadata, or source bookkeeping.\n\n## Tags\n\nTags can apply to either the definition or an individual record.\n\nUse definition tags for stable categories that describe the annotation itself:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Medication Taken\" \\\n --tag health \\\n --tag adherence\n```\n\nUse record tags for context that only applies to one event:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Medication Taken\" \\\n --note \"Backfilled after travel\" \\\n --tag backfill \\\n --tag travel\n```\n\nUse short, reusable, lowercase tags such as `health`, `agent`, `research`, `new-task`, `manual-test`, or `backfill`. Tags should be filter dimensions. For geography, prefer actual place tags such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus`, not abstract scope labels. Do not put timestamps, private notes, dedupe keys, or one-off sentences in tags.\n\n## Safety\n\n- Do not print access tokens, direct capability URLs, or private Fulcra records in chat or logs.\n- Use dry-run mode before risky writes.\n- Ask before changing an existing annotation definition.\n- The bundled helper does not expose destructive definition deletes; use a separate reviewed admin workflow for deletion.\n\nFile v1.0.15:_meta.json\n\n{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.15\",\n \"publishedAt\": 1783854226163\n}\n\nFile v1.0.15:references/api-notes.md\n\n# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe **preferred** ingest endpoint is the typed path (what the bundled helper now uses,\nverified 2026-07-10):\n\n`POST /ingest/v1/record/{data_type}` — `{data_type}` is a **base** type path segment\n(e.g. `MomentAnnotation`, `ScaleAnnotation`). The body is the **unwrapped** record —\nNOT the legacy `DataRecordV1` envelope. `Content-Type: application/json` for one\nrecord (or `application/x-jsonl`, one record per line, for a batch); a content-length\nheader is required. Success is **201 → `{\"upload_id\": \"\"}`**.\n\nThe schema is **closed**: only a fixed served set survives; any other key is dropped\nsilently (still 201, field gone). Verified served sets (api_version `v1alpha1`):\n\n- `MomentAnnotation`, `DurationAnnotation`: `{note, recorded_at, tags, sources, id}`\n- `BooleanAnnotation`, `NumericAnnotation`, `ScaleAnnotation`: also `value`, `unit`\n\n`note` is the only free-form slot. Reference a custom definition in `sources` as\n`com.fulcradynamics.annotation.` — it is NOT a path segment\n(`/ingest/v1/record/MomentAnnotation/` returns 404). Discover the exact\napi_version + served set from the catalog: `GET /data/v1/catalog`, then\n`GET /data/v1/catalog/{data_type}/{api_version}/schema`.\n\nTyped body example (ScaleAnnotation):\n\n```json\n{\n \"note\": \"optional note\",\n \"value\": 4,\n \"recorded_at\": \"2026-07-10T19:30:00Z\",\n \"sources\": [\"com.example.agent\", \"com.fulcradynamics.annotation.\"],\n \"tags\": []\n}\n```\n\n**Legacy (retirement-eligible):** `POST /ingest/v1/record` with the `DataRecordV1`\nenvelope (`{specversion, data:\"\", metadata:{data_type, recorded_at,\nsource, tags, content_type}}`) is still published and returns `204`, but prefer the\ntyped path for new code. Envelope differences: `source` (singular) vs `sources`, and\nthe payload rides as a JSON string in `data` rather than top-level fields.\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Write Semantics\n\nThe typed path returns **201** (`{\"upload_id\": ...}`); the legacy path returns `204`.\nEither way acceptance is **provisional and async** — a record takes ~1-2 minutes to\nbecome visible, so the success status is NOT proof-of-persistence. Confirm by reading\nback the expected annotation class and matching the source id (inside `sources`) in a\nnarrow time window on a **later** pass, not inline. There is **no server-side dedup**,\nso retries after an ambiguous response can duplicate — guard with a client-side\nidempotency key. Invalid `application/x-jsonl` lines are dropped **silently** (the\nbatch still 201s, with no per-line errors and no status endpoint).\n\nDefinition tag updates are replacement-style in the helper: pass the full desired tag set to `update --tag ...`; do not assume partial add/remove semantics.\n\n## Current Gaps\n\nFulcra CLI 0.1.36 exposes annotation definition and tag management through `data-type` and `tag` command groups. Prefer those or the Python lib for definitions/tags when available. Timeline record write/delete/replace commands are still absent, so records remain ingest-backed and must be verified with readback.\n\nDefinition reads can also use `uv tool run fulcra-api catalog`, and user-defined records can be read with `uv tool run fulcra-api get-records` using the user-defined data type identifier.\n\nThe live OpenAPI surface exposes versioned catalog/schema endpoints:\n\n- `GET /data/v1/catalog/{data_type}/{api_version}`\n- `GET /data/v1/catalog/{data_type}/{api_version}/schema`\n\nUse these for payload-shape checks before adding support for a new annotation type or measurement unit. Do not paste full private schema/debug output into chat.\n\nFile v1.0.15:skill-card.md\n\n## Description:
\nCreate, list, update, and record Fulcra annotations through the Fulcra Life API.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agent users use this skill to create reusable Fulcra annotation definitions and record approved moment, boolean, numeric, or scale annotation events. It is intended for workflows that need to write and verify Fulcra annotation records from an authenticated user account.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can write or update data in a user's Fulcra account.
\nMitigation: Use it only with an authenticated account the user controls, ask before updating existing definitions, and run dry-run before risky writes.
\nRisk: Fulcra annotations may contain personal or sensitive context.
\nMitigation: Avoid public or shared chats with real personal data unless the user explicitly approves, and do not print tokens, credential files, or raw private Fulcra records.
\nRisk: Record ingest is asynchronous, so an accepted write is not immediate proof that the record is visible.
\nMitigation: Verify writes by reading records back and treat success as confirmed only after the expected record is found.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations)
\n- [Publisher profile](https://clawhub.ai/user/arc-claw-bot)
\n- [Fulcra Annotation API Notes](references/api-notes.md)
\n- [Fulcra OpenAPI document](https://api.fulcradynamics.com/openapi.json)
\n\n\n## Skill Output:
\n**Output Type(s):** [guidance, shell commands, configuration, code, text]
\n**Output Format:** [Markdown with inline shell commands and JSON command output]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires local Fulcra CLI authentication and user approval for writes; write confirmation depends on later readback.]
\n\n## Skill Version(s):
\n1.0.15 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.15:agents/openai.yaml\n\ninterface:\n display_name: \"Fulcra Annotations\"\n short_description: \"Create, list, and record Fulcra annotations from agents.\"\n default_prompt: \"Create or record a Fulcra annotation.\"\n\nArchive v1.0.14: 7 files, 17285 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6544b), references/api-notes.md (3397b), scripts/fulcra_annotations.py (18886b), skill-card.md (2395b), SKILL.md (16982b), _meta.json (138b)\n\nFile v1.0.14:SKILL.md\n\n---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the highest-level supported surface for each operation:\n\n- For annotation definitions and tags, prefer `uv tool run fulcra-api data-type ...` and `uv tool run fulcra-api tag ...`, or the equivalent `fulcra_api` Python helpers, when shell/Python is available.\n- For annotation timeline records, use the bundled script or an ingest-backed helper with readback verification. Fulcra CLI 0.1.35 still does not expose record write/delete/replace commands.\n- Do not hand-write curl calls unless the CLI/lib and bundled script are both missing the required capability.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` or `Asked Agent to Do Something New`. Created once with `create`.\n- **Annotation record**: one logged occurrence/value of a definition. Written with `record`.\n- **Moment annotation**: an event with no value. Use for \"this happened\" logs.\n- **Boolean/numeric/scale annotations**: metric-like records that require `--value`.\n- **Definition tags**: reusable labels stored on the annotation definition. Add them when creating the definition with repeated `create --tag`.\n- **Record tags**: labels stored on one specific record. Add them when recording with repeated `record --tag`.\n- **Tag resolution**: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and creates missing tag names automatically.\n- **Historical record**: any record whose event time is not now. Always pass `--recorded-at`.\n- **Confirmed write**: a record is not confirmed until readback finds `verified_matches >= 1`.\n\n## Safety Rules\n\n- Never print access tokens, refresh tokens, raw private Fulcra records, credential files, or direct capability URLs in chat.\n- Device auth URLs and user codes are allowed only when the intended user needs to approve Fulcra access from another device; send them only through the active trusted user channel.\n- Ask before deleting or updating an existing annotation definition.\n- For public demos, use synthetic annotation names/values unless the user explicitly approves real data.\n- Do not claim a write succeeded from HTTP status alone. Check the script result and verify readback.\n- Duration annotations are only partially supported by this skill; prefer moment/boolean/numeric/scale until Fulcra documents duration ingest shape more clearly.\n\n## Auth\n\nThe script gets auth from a trusted secret manager token when `FULCRA_ACCESS_TOKEN` is set, otherwise from the locally authenticated Fulcra CLI command configured by `FULCRA_CLI_COMMAND`.\n\nFulcra requires an authenticated account, not an API key. Accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nAuthenticate first:\n\n```bash\nuv tool run fulcra-api auth login\n```\n\nFor remote agents, keep the CLI running, surface the printed device authorization URL and code to the intended user in chat through the active trusted user channel, and wait for approval. The user can open the URL from any browser on any device. After approval, verify auth with a non-token command such as `uv tool run fulcra-api user-info`; do not paste tokens into chat.\n\nSet `FULCRA_HOME=/path/to/home` if credentials are not under the process `HOME`.\n\n## Common Commands\n\nList annotation definitions before creating a new one:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCheck first-class definition and tag surfaces:\n\n```bash\nuv tool run fulcra-api data-type --help\nuv tool run fulcra-api tag --help\nuv tool run fulcra-api catalog --base-types-only\n```\n\nUse live help for exact type names and options before creating definitions with `data-type create`.\n\nCreate a moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nUse `create --tag` more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as `agent`, `health`, or `research`. The script resolves tag names to Fulcra tag IDs before sending the API payload.\n\nRecord a moment annotation now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nUse `record --tag` more than once to attach tags to the individual record. If `record --tag` is omitted, the record inherits the definition tags. If `record --tag` is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.\n\nRecord a historical moment annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\"\n```\n\nUse a full ISO-8601 timestamp with timezone for historical writes. If the user says \"yesterday at 10am\", resolve it in the user's timezone and pass the offset explicitly, for example `2026-05-15T10:00:00-04:00`. Fulcra readback may show the equivalent UTC time, such as `2026-05-15T14:00:00+00:00`.\n\nRecord by annotation ID when names are ambiguous:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\"\n```\n\nCreate a 1-5 scale annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type scale \\\n --name \"Focus\" \\\n --description \"How focused do I feel right now?\" \\\n --scale-labels \"1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In\" \\\n --default-value 3\n```\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor measurements with specialized units, inspect the live schema through the bundled helper before creating the definition and then prefer adding script support over ad hoc API calls:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw schema output into chat if it includes private account context.\n\nRecord a scale/numeric/boolean value:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" \\\n --value 4 \\\n --note \"Deep work block started well\"\n```\n\nRead back recent records for verification:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent \\\n --name \"Asked Agent to Do Something New\" \\\n --hours 72 \\\n --limit 20\n```\n\nUpdate definition metadata or replace definition tags only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag workflow \\\n --tag agent\n```\n\nDelete a definition only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\nDry-run any write before sending it:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" --value 4 --dry-run\n```\n\n## Workflow\n\n1. Determine the annotation type: moment, boolean, numeric, or scale. Prefer moment for \"this happened\".\n2. Decide whether tags belong on the definition, the individual record, or both.\n3. Run `list` and check whether the definition already exists.\n4. If an existing definition needs a metadata or tag change, ask for approval and use `update --id ...`; dry-run first for broad retagging.\n5. If the definition is missing and the user asked to create/log that annotation, run `create`.\n6. Record with `record --name ...` or `record --id ...`.\n7. For historical writes, always include `--recorded-at \"\"`.\n8. Trust only a successful script result with `verified_matches >= 1` for confirmed writes.\n9. If verification fails after ingest returns `204`, wait briefly and rerun `recent --id ` or `recent --name \"\" --hours `.\n10. Report the exact timestamp written and the readback timestamp. Do not include tokens, direct capability URLs, or unnecessary private record data.\n\n## Demo and Handoff Pattern\n\nFor onboarding, the first verified record should lead to a small payoff instead of a dry \"done\" message.\n\n- Offer 2-3 visual directions and ask the user to choose before generating a dashboard or artifact.\n- Keep demo files local to the workspace and avoid dumping raw HTML or raw Fulcra records into chat.\n- Use the verified annotation name, timestamp, value, and a short interpretation. Avoid exposing unrelated Fulcra data.\n- Make the next steps concrete: install/open the Context app for mobile logging, inspect data in Context Web, add another annotation, or iterate on the dashboard.\n- In public or group-chat demos, use synthetic values unless the user explicitly approved sharing real values.\n\n## Idempotent Writer Pattern\n\nFor automated or backfilled annotation pipelines, use an append-only, ledger-backed writer:\n\n1. Normalize the source event into stable fields: annotation name/id, event timestamp, source, severity/category, value/note, and any real filter dimensions.\n2. Generate a dedupe key from stable source facts. Keep this key in local state, metadata, or source bookkeeping; do not place it in the visible note.\n3. Check the local ledger before writing. Skip `verified`, retry `pending` or `failed`, and write only unseen keys.\n4. Treat ingest HTTP success as provisional. Confirm with `record` output or `recent` readback and mark the ledger `verified` only when `verified_matches >= 1`.\n5. For changed source events, avoid duplicate annotations unless the change is materially new. Prefer a follow-up annotation for escalation/resolution over rewriting history.\n\n## Tag Rules\n\n- Use definition tags for stable classification of the annotation itself, such as `health`, `agent`, `research`, or `workflow`.\n- Use record tags for context that applies only to one logged occurrence, such as `new-task`, `manual-test`, `backfill`, or `user-requested`.\n- Add definition tags with `create --tag `. Repeat `--tag` for multiple definition tags.\n- Add record tags with `record --tag `. Repeat `--tag` for multiple record tags.\n- `--tag` accepts either a Fulcra tag name or an existing tag UUID.\n- Fulcra stores tags as UUIDs. The script resolves tag names to UUIDs and creates a missing tag name automatically.\n- If `record --tag` is omitted, the record uses the definition tags.\n- If `record --tag` is provided, the explicit record tags are sent for that record.\n- Use lowercase, short, reusable tags. Prefer `new-task` over a full sentence.\n- Tags should be filter dimensions, not prose. For places, prefer actual geography such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus` over abstract tags such as `scope-town` or `scope-neighborhood`.\n- Pair place tags with category/source/severity tags when useful, for example `category-traffic`, `source-town-feed`, or `severity-advisory`.\n- Do not use tags for timestamps, detailed notes, values, people names, dedupe keys, or private context. Use `--recorded-at`, `--note`, `--value`, `--source`, and local metadata/ledger state for those.\n- Existing definitions can be retagged with `update --id ... --tag ...` after user approval; `--tag` replaces the definition tag set.\n\n## Timestamp Rules\n\n- If `--recorded-at` is omitted, the script records the annotation at the current time.\n- If the user asks for a historical or scheduled-looking time, pass `--recorded-at`.\n- Use the user's local timezone when resolving relative phrases like \"yesterday at 10am\".\n- Include the timezone offset in the timestamp. Do not pass naive local times.\n- UTC readback is expected. Compare instants, not string equality.\n\nExample: on 2026-05-16 in Eastern Time, \"yesterday at 10am\" means `2026-05-15T10:00:00-04:00`, which readback may show as `2026-05-15T14:00:00+00:00`.\n\n## Verification Rules\n\n- `record` returns `recorded_at` and `verified_matches`.\n- `verified_matches >= 1` means the script found the written record in Fulcra after ingest.\n- For historical writes, use `recent --hours` with a window large enough to include the target time if a second verification is needed.\n- When inspecting readback, use only minimal fields needed for confirmation: annotation name/id, `recorded_at`, value if relevant, and note if relevant.\n\n## API Notes\n\nCore REST endpoints:\n\n- `GET /user/v1alpha1/annotation` lists annotation definitions.\n- `POST /user/v1alpha1/annotation` creates a definition.\n- `PUT /user/v1alpha1/annotation/{annotation_id}` updates a definition.\n- `DELETE /user/v1alpha1/annotation/{annotation_id}` deletes a definition.\n- `POST /ingest/v1/record` records annotation events.\n- `POST /ingest/v1/record/{data_type}` is the typed ingest path when the OpenAPI schema for that data type is known.\n- `POST /ingest/v1/record/batch` records batches of annotation events.\n- Readback uses `/data/v1alpha1/event/MomentAnnotation` for moment/duration and `/data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation}` for metric annotation values.\n\nFulcra CLI 0.1.35 exposes annotation definition and tag management through `data-type` and `tag` command groups. Prefer those or the Python lib for definitions/tags when available. Timeline record write/delete/replace commands are still absent, so records remain ingest-backed and must be verified with readback.\n\nBefore building a new annotation data type or a typed-ingest helper, inspect the live OpenAPI catalog/schema endpoints:\n\n```text\nGET /data/v1/catalog/{data_type}/{api_version}\nGET /data/v1/catalog/{data_type}/{api_version}/schema\n```\n\nDo not infer payload shape from examples alone. Treat OpenAPI/main drift as a watch signal until the released CLI/lib or a direct schema check confirms the shape.\n\nFor schema details or upstream gaps, read `references/api-notes.md`.\n\nFile v1.0.14:README.md\n\n# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates, updates, and deletes annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed, or `FULCRA_ACCESS_TOKEN` supplied by a trusted secret manager.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. Set `FULCRA_CLI_COMMAND` only when you need to override the default `uv tool run fulcra-api` command.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nFor definition and tag management, prefer the current Fulcra CLI/lib surfaces when available:\n\n```bash\nuv tool run fulcra-api data-type --help\nuv tool run fulcra-api tag --help\n```\n\nTimeline record writes still use ingest-backed helpers and must be verified with readback.\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at least `1`.\n\n## First-Run Flow\n\nFor a new user, keep the first annotation loop tight:\n\n1. Offer 2-3 concrete tracking ideas instead of asking an open-ended question.\n2. Check auth with `uv tool run fulcra-api user-info`; if needed, run `uv tool run fulcra-api auth login` and send only the device URL/code.\n3. Create 1-3 definitions, saving the returned `annotation.id`, `source_id`, and type in your working notes.\n4. Ask one direct question, record the first value with `record --id ...`, and verify `verified_matches >= 1`.\n5. Hand off with the definitions created, the timestamp written, and a concrete next step such as mobile logging, Context Web, another annotation, or a small dashboard.\n\nFor public demos or group chats, use synthetic values unless the user explicitly approves sharing real Fulcra records.\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor specialized measurement units, inspect the live schema through the bundled helper before adding script support:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw private account output into chat.\n\nUpdate or delete definitions only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag health \\\n --tag workflow\n\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\n## Idempotent Pipelines\n\nFor recurring imports or backfills, keep a local ledger keyed by stable source facts. Write unseen records once, retry pending/failed records, and mark a record verified only after Fulcra readback. Keep dedupe keys out of visible notes; store them in local state, metadata, or source bookkeeping.\n\n## Tags\n\nTags can apply to either the definition or an individual record.\n\nUse definition tags for stable categories that describe the annotation itself:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Medication Taken\" \\\n --tag health \\\n --tag adherence\n```\n\nUse record tags for context that only applies to one event:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Medication Taken\" \\\n --note \"Backfilled after travel\" \\\n --tag backfill \\\n --tag travel\n```\n\nUse short, reusable, lowercase tags such as `health`, `agent`, `research`, `new-task`, `manual-test`, or `backfill`. Tags should be filter dimensions. For geography, prefer actual place tags such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus`, not abstract scope labels. Do not put timestamps, private notes, dedupe keys, or one-off sentences in tags.\n\n## Safety\n\n- Do not print access tokens, direct capability URLs, or private Fulcra records in chat or logs.\n- Use dry-run mode before risky writes.\n- Ask before deleting or changing an existing annotation definition.\n\nFile v1.0.14:_meta.json\n\n{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.14\",\n \"publishedAt\": 1783622358586\n}\n\nFile v1.0.14:references/api-notes.md\n\n# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n- `DELETE /user/v1alpha1/annotation/{annotation_id}`\n- `POST /user/v1alpha1/annotation/{annotation_id}/cancel_deletion`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe generic ingest endpoint is:\n\n`POST /ingest/v1/record`\n\nThe live OpenAPI surface also includes a typed ingest endpoint:\n\n`POST /ingest/v1/record/{data_type}`\n\nUse typed ingest only after resolving the exact data type and API version from the live catalog/schema surface. Keep the generic ingest path as the conservative default for the bundled helper until typed annotation payloads have been smoke-tested and readback-verified.\n\nPayload shape:\n\n```json\n{\n \"specversion\": 1,\n \"data\": \"{\\\"note\\\":\\\"optional note\\\",\\\"value\\\":4}\",\n \"metadata\": {\n \"data_type\": \"ScaleAnnotation\",\n \"recorded_at\": \"2026-05-14T19:30:00Z\",\n \"source\": [\n \"com.example.agent\",\n \"com.fulcradynamics.annotation.\"\n ],\n \"tags\": [],\n \"content_type\": \"application/json\"\n }\n}\n```\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Write Semantics\n\n`POST /ingest/v1/record` returning `204` means the ingest request was accepted; it is not enough to claim user-visible success. Confirm writes by reading back the expected annotation class and matching the annotation source ID inside a narrow time window.\n\n`POST /ingest/v1/record/{data_type}` has the same verification rule: accept/write status is provisional until record readback proves the expected record exists.\n\n`POST /ingest/v1/record/batch` accepts batched records. Treat batch ingest acceptance as provisional until readback verifies the expected records.\n\nDefinition tag updates are replacement-style in the helper: pass the full desired tag set to `update --tag ...`; do not assume partial add/remove semantics.\n\n## Current Gaps\n\nFulcra CLI 0.1.35 exposes annotation definition and tag management through `data-type` and `tag` command groups. Prefer those or the Python lib for definitions/tags when available. Timeline record write/delete/replace commands are still absent, so records remain ingest-backed and must be verified with readback.\n\nDefinition reads can also use `uv tool run fulcra-api catalog`, and user-defined records can be read with `uv tool run fulcra-api get-records` using the user-defined data type identifier.\n\nThe live OpenAPI surface exposes versioned catalog/schema endpoints:\n\n- `GET /data/v1/catalog/{data_type}/{api_version}`\n- `GET /data/v1/catalog/{data_type}/{api_version}/schema`\n\nUse these for payload-shape checks before adding support for a new annotation type or measurement unit. Do not paste full private schema/debug output into chat.\n\nFile v1.0.14:skill-card.md\n\n## Description:
\nCreate, list, update, and record Fulcra annotations through the Fulcra Life API.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agents use this skill to create Fulcra annotation definitions, record user-approved moments or values, and verify that writes are visible through Fulcra readback.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can use local Fulcra credentials to read, write, update, or delete external Fulcra annotation data.
\nMitigation: Install only in trusted runtime environments, keep credentials out of chat and logs, and require explicit user confirmation before update or delete operations.
\nRisk: Environment-controlled settings can redirect the API base or override the Fulcra CLI command used for authentication.
\nMitigation: Keep FULCRA_API_BASE and FULCRA_CLI_COMMAND unset unless intentionally needed, and review those values before running write operations.
\nRisk: Accepted ingest requests may not prove that a record is visible to the user.
\nMitigation: Use dry-run before writes and treat a record as confirmed only when readback verification reports verified_matches of at least 1.
\n\n\n## Reference(s):
\n- [Fulcra Annotations ClawHub page](https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations)
\n- [Fulcra Annotation API Notes](references/api-notes.md)
\n- [Fulcra OpenAPI document](https://api.fulcradynamics.com/openapi.json)
\n\n\n## Skill Output:
\n**Output Type(s):** [Guidance, Shell commands, Configuration, JSON]
\n**Output Format:** [Markdown guidance with shell commands and JSON command results]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Outputs may include Fulcra annotation IDs, source IDs, timestamps, dry-run payloads, and readback verification counts.]
\n\n## Skill Version(s):
\n1.0.14 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.14:agents/openai.yaml\n\ninterface:\n display_name: \"Fulcra Annotations\"\n short_description: \"Create, list, and record Fulcra annotations from agents.\"\n default_prompt: \"Create or record a Fulcra annotation.\"\n\nArchive v1.0.13: 7 files, 16286 bytes\n\nFiles: agents/openai.yaml (255b), README.md (6270b), references/api-notes.md (1589b), scripts/fulcra_annotations.py (16507b), skill-card.md (2855b), SKILL.md (16511b), _meta.json (138b)\n\nFile v1.0.13:SKILL.md\n\n---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"uv\"]},\"permissions\":[\"shell:uv-tool-run-fulcra-api\",\"network:https://api.fulcradynamics.com\",\"env:FULCRA_ACCESS_TOKEN\",\"env:FULCRA_HOME\",\"env:FULCRA_AGENT_SOURCE\"]}}\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the bundled script first. Do not hand-write curl calls unless the script is missing a required capability, because the script keeps tokens out of chat, builds the Fulcra ingest payload consistently, and performs readback verification.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` or `Asked Agent to Do Something New`. Created once with `create`.\n- **Annotation record**: one logged occurrence/value of a definition. Written with `record`.\n- **Moment annotation**: an event with no value. Use for \"this happened\" logs.\n- **Boolean/numeric/scale annotations**: metric-like records that require `--value`.\n- **Definition tags**: reusable labels stored on the annotation definition. Add them when creating the definition with repeated `create --tag`.\n- **Record tags**: labels stored on one specific record. Add them when recording with repeated `record --tag`.\n- **Tag resolution**: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and creates missing tag names automatically.\n- **Historical record**: any record whose event time is not now. Always pass `--recorded-at`.\n- **Confirmed write**: a record is not confirmed until readback finds `verified_matches >= 1`.\n\n## Safety Rules\n\n- Never print access tokens, refresh tokens, raw private Fulcra records, credential files, or direct capability URLs in chat.\n- Authenticated API calls are pinned to `https://api.fulcradynamics.com`; do not redirect Fulcra bearer tokens to custom API hosts.\n- `FULCRA_CLI_COMMAND` is restricted to the standard Fulcra CLI invocation (`uv tool run fulcra-api`, `fulcra-api`, or a trusted absolute path ending in `fulcra-api`).\n- Device auth URLs and user codes are allowed only when the intended user needs to approve Fulcra access from another device; send them only through the active trusted user channel.\n- Ask before deleting or updating an existing annotation definition.\n- For public demos, use synthetic annotation names/values unless the user explicitly approves real data.\n- Do not claim a write succeeded from HTTP status alone. Check the script result and verify readback.\n- Duration annotations are only partially supported by this skill; prefer moment/boolean/numeric/scale until Fulcra documents duration ingest shape more clearly.\n\n## Auth\n\nThe script gets auth from a trusted secret manager token when `FULCRA_ACCESS_TOKEN` is set, otherwise from the locally authenticated Fulcra CLI command configured by `FULCRA_CLI_COMMAND`.\n\nFulcra requires an authenticated account, not an API key. Accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nAuthenticate first:\n\n```bash\nuv tool run fulcra-api auth login\n```\n\nFor remote agents, keep the CLI running, surface the printed device authorization URL and code to the intended user in chat through the active trusted user channel, and wait for approval. The user can open the URL from any browser on any device. After approval, verify auth with a non-token command such as `uv tool run fulcra-api user-info`; do not paste tokens into chat.\n\nSet `FULCRA_HOME=/path/to/home` if credentials are not under the process `HOME`.\n\n## Common Commands\n\nList annotation definitions before creating a new one:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nUse `create --tag` more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as `agent`, `health`, or `research`. The script resolves tag names to Fulcra tag IDs before sending the API payload.\n\nRecord a moment annotation now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nUse `record --tag` more than once to attach tags to the individual record. If `record --tag` is omitted, the record inherits the definition tags. If `record --tag` is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.\n\nRecord a historical moment annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\"\n```\n\nUse a full ISO-8601 timestamp with timezone for historical writes. If the user says \"yesterday at 10am\", resolve it in the user's timezone and pass the offset explicitly, for example `2026-05-15T10:00:00-04:00`. Fulcra readback may show the equivalent UTC time, such as `2026-05-15T14:00:00+00:00`.\n\nRecord by annotation ID when names are ambiguous:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\"\n```\n\nCreate a 1-5 scale annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type scale \\\n --name \"Focus\" \\\n --description \"How focused do I feel right now?\" \\\n --scale-labels \"1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In\" \\\n --default-value 3\n```\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor measurements with specialized units, inspect the live schema through the bundled helper before creating the definition and then prefer adding script support over ad hoc API calls:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw schema output into chat if it includes private account context.\n\nRecord a scale/numeric/boolean value:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" \\\n --value 4 \\\n --note \"Deep work block started well\"\n```\n\nRead back recent records for verification:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent \\\n --name \"Asked Agent to Do Something New\" \\\n --hours 72 \\\n --limit 20\n```\n\nUpdate definition metadata or replace definition tags only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag workflow \\\n --tag agent\n```\n\nDelete a definition only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\nDry-run any write before sending it:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" --value 4 --dry-run\n```\n\n## Workflow\n\n1. Determine the annotation type: moment, boolean, numeric, or scale. Prefer moment for \"this happened\".\n2. Decide whether tags belong on the definition, the individual record, or both.\n3. Run `list` and check whether the definition already exists.\n4. If an existing definition needs a metadata or tag change, ask for approval and use `update --id ...`; dry-run first for broad retagging.\n5. If the definition is missing and the user asked to create/log that annotation, run `create`.\n6. Record with `record --name ...` or `record --id ...`.\n7. For historical writes, always include `--recorded-at \"\"`.\n8. Trust only a successful script result with `verified_matches >= 1` for confirmed writes.\n9. If verification fails after ingest returns `204`, wait briefly and rerun `recent --id ` or `recent --name \"\" --hours `.\n10. Report the exact timestamp written and the readback timestamp. Do not include tokens, direct capability URLs, or unnecessary private record data.\n\n## Demo and Handoff Pattern\n\nFor onboarding, the first verified record should lead to a small payoff instead of a dry \"done\" message.\n\n- Offer 2-3 visual directions and ask the user to choose before generating a dashboard or artifact.\n- Keep demo files local to the workspace and avoid dumping raw HTML or raw Fulcra records into chat.\n- Use the verified annotation name, timestamp, value, and a short interpretation. Avoid exposing unrelated Fulcra data.\n- Make the next steps concrete: install/open the Context app for mobile logging, inspect data in Context Web, add another annotation, or iterate on the dashboard.\n- In public or group-chat demos, use synthetic values unless the user explicitly approved sharing real values.\n\n## Idempotent Writer Pattern\n\nFor automated or backfilled annotation pipelines, use an append-only, ledger-backed writer:\n\n1. Normalize the source event into stable fields: annotation name/id, event timestamp, source, severity/category, value/note, and any real filter dimensions.\n2. Generate a dedupe key from stable source facts. Keep this key in local state, metadata, or source bookkeeping; do not place it in the visible note.\n3. Check the local ledger before writing. Skip `verified`, retry `pending` or `failed`, and write only unseen keys.\n4. Treat ingest HTTP success as provisional. Confirm with `record` output or `recent` readback and mark the ledger `verified` only when `verified_matches >= 1`.\n5. For changed source events, avoid duplicate annotations unless the change is materially new. Prefer a follow-up annotation for escalation/resolution over rewriting history.\n\n## Tag Rules\n\n- Use definition tags for stable classification of the annotation itself, such as `health`, `agent`, `research`, or `workflow`.\n- Use record tags for context that applies only to one logged occurrence, such as `new-task`, `manual-test`, `backfill`, or `user-requested`.\n- Add definition tags with `create --tag `. Repeat `--tag` for multiple definition tags.\n- Add record tags with `record --tag `. Repeat `--tag` for multiple record tags.\n- `--tag` accepts either a Fulcra tag name or an existing tag UUID.\n- Fulcra stores tags as UUIDs. The script resolves tag names to UUIDs and creates a missing tag name automatically.\n- If `record --tag` is omitted, the record uses the definition tags.\n- If `record --tag` is provided, the explicit record tags are sent for that record.\n- Use lowercase, short, reusable tags. Prefer `new-task` over a full sentence.\n- Tags should be filter dimensions, not prose. For places, prefer actual geography such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus` over abstract tags such as `scope-town` or `scope-neighborhood`.\n- Pair place tags with category/source/severity tags when useful, for example `category-traffic`, `source-town-feed`, or `severity-advisory`.\n- Do not use tags for timestamps, detailed notes, values, people names, dedupe keys, or private context. Use `--recorded-at`, `--note`, `--value`, `--source`, and local metadata/ledger state for those.\n- Existing definitions can be retagged with `update --id ... --tag ...` after user approval; `--tag` replaces the definition tag set.\n\n## Timestamp Rules\n\n- If `--recorded-at` is omitted, the script records the annotation at the current time.\n- If the user asks for a historical or scheduled-looking time, pass `--recorded-at`.\n- Use the user's local timezone when resolving relative phrases like \"yesterday at 10am\".\n- Include the timezone offset in the timestamp. Do not pass naive local times.\n- UTC readback is expected. Compare instants, not string equality.\n\nExample: on 2026-05-16 in Eastern Time, \"yesterday at 10am\" means `2026-05-15T10:00:00-04:00`, which readback may show as `2026-05-15T14:00:00+00:00`.\n\n## Verification Rules\n\n- `record` returns `recorded_at` and `verified_matches`.\n- `verified_matches >= 1` means the script found the written record in Fulcra after ingest.\n- `uv tool run fulcra-api data-updates ` can show that annotation-related data types were processed in a time range, but it is not record-level write verification. Do not use update counts as proof that a specific annotation record was created, changed, or deleted.\n- For historical writes, use `recent --hours` with a window large enough to include the target time if a second verification is needed.\n- When inspecting readback, use only minimal fields needed for confirmation: annotation name/id, `recorded_at`, value if relevant, and note if relevant.\n\n## API Notes\n\nCore REST endpoints:\n\n- `GET /user/v1alpha1/annotation` lists annotation definitions.\n- `POST /user/v1alpha1/annotation` creates a definition.\n- `PUT /user/v1alpha1/annotation/{annotation_id}` updates a definition.\n- `DELETE /user/v1alpha1/annotation/{annotation_id}` deletes a definition.\n- `POST /ingest/v1/record` records annotation events.\n- `POST /ingest/v1/record/batch` records batches of annotation events.\n- Readback uses `/data/v1alpha1/event/MomentAnnotation` for moment/duration and `/data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation}` for metric annotation values.\n\nFor bulk or backfill pipelines, `data-updates` is a coarse freshness diagnostic after ingest. It supplements the local ledger and record readback; it does not replace either.\n\nFor schema details or upstream gaps, read `references/api-notes.md`.\n\nFile v1.0.13:README.md\n\n# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates, updates, and deletes annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed, or `FULCRA_ACCESS_TOKEN` supplied by a trusted secret manager.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. Set `FULCRA_CLI_COMMAND` only when you need to override the default `uv tool run fulcra-api` command.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at least `1`.\n\n## First-Run Flow\n\nFor a new user, keep the first annotation loop tight:\n\n1. Offer 2-3 concrete tracking ideas instead of asking an open-ended question.\n2. Check auth with `uv tool run fulcra-api user-info`; if needed, run `uv tool run fulcra-api auth login` and send only the device URL/code.\n3. Create 1-3 definitions, saving the returned `annotation.id`, `source_id`, and type in your working notes.\n4. Ask one direct question, record the first value with `record --id ...`, and verify `verified_matches >= 1`.\n5. Hand off with the definitions created, the timestamp written, and a concrete next step such as mobile logging, Context Web, another annotation, or a small dashboard.\n\nFor public demos or group chats, use synthetic values unless the user explicitly approves sharing real Fulcra records.\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor specialized measurement units, inspect the live schema through the bundled helper before adding script support:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw private account output into chat.\n\nUpdate or delete definitions only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag health \\\n --tag workflow\n\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\n## Idempotent Pipelines\n\nFor recurring imports or backfills, keep a local ledger keyed by stable source facts. Write unseen records once, retry pending/failed records, and mark a record verified only after Fulcra readback. Keep dedupe keys out of visible notes; store them in local state, metadata, or source bookkeeping.\n\n## Tags\n\nTags can apply to either the definition or an individual record.\n\nUse definition tags for stable categories that describe the annotation itself:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Medication Taken\" \\\n --tag health \\\n --tag adherence\n```\n\nUse record tags for context that only applies to one event:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Medication Taken\" \\\n --note \"Backfilled after travel\" \\\n --tag backfill \\\n --tag travel\n```\n\nUse short, reusable, lowercase tags such as `health`, `agent`, `research`, `new-task`, `manual-test`, or `backfill`. Tags should be filter dimensions. For geography, prefer actual place tags such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus`, not abstract scope labels. Do not put timestamps, private notes, dedupe keys, or one-off sentences in tags.\n\n## Safety\n\n- Do not print access tokens, direct capability URLs, or private Fulcra records in chat or logs.\n- Use dry-run mode before risky writes.\n- Ask before deleting or changing an existing annotation definition.\n\nFile v1.0.13:_meta.json\n\n{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.13\",\n \"publishedAt\": 1783006155753\n}\n\nFile v1.0.13:references/api-notes.md\n\n# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n- `DELETE /user/v1alpha1/annotation/{annotation_id}`\n- `POST /user/v1alpha1/annotation/{annotation_id}/cancel_deletion`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe generic ingest endpoint is:\n\n`POST /ingest/v1/record`\n\nPayload shape:\n\n```json\n{\n \"specversion\": 1,\n \"data\": \"{\\\"note\\\":\\\"optional note\\\",\\\"value\\\":4}\",\n \"metadata\": {\n \"data_type\": \"ScaleAnnotation\",\n \"recorded_at\": \"2026-05-14T19:30:00Z\",\n \"source\": [\n \"com.example.agent\",\n \"com.fulcradynamics.annotation.\"\n ],\n \"tags\": [],\n \"content_type\": \"application/json\"\n }\n}\n```\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Current Gaps\n\nThe beta CLI currently does not expose annotation write commands or Magic Link retrieval. Prefer the bundled REST script until upstream CLI support lands.\n\nFile v1.0.13:skill-card.md\n\n## Description:
\nFulcra Annotations lets an agent create, list, update, delete, record, and verify Fulcra annotation definitions and events through the Fulcra Life API.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nUse this skill when a user wants an agent to set up reusable Fulcra annotation definitions, log approved moment, boolean, numeric, or scale annotation records, inspect annotation identifiers, or build a workflow that writes and verifies Fulcra annotations.
\n\n### Deployment Geography for Use:
\nGlobal, subject to Fulcra account availability, network access to https://api.fulcradynamics.com, and the user's local privacy and compliance requirements.
\n\n## Known Risks and Mitigations:
\nRisk: Annotation values and notes may become persistent personal data in the user's Fulcra account.
\nMitigation: Install only for user-directed Fulcra annotation work, review write prompts before approval, and avoid real private data in public demos.
\nRisk: Deletion or changes to existing annotation definitions could alter a user's tracking setup.
\nMitigation: Ask for explicit user approval before update or delete operations and use dry-run mode before risky writes.
\nRisk: Fulcra credentials or private records could be exposed through chat or logs if handled carelessly.
\nMitigation: Do not print tokens, credential files, direct capability URLs, or raw private records; use the trusted CLI or secret-manager token flow.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations)
\n- [Fulcra API OpenAPI document](https://api.fulcradynamics.com/openapi.json)
\n- [Publisher profile](https://clawhub.ai/user/arc-claw-bot)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, shell commands, configuration, guidance]
\n**Output Format:** [Agent guidance plus JSON-producing command-line helper operations for Fulcra annotation definitions and records.]
\n**Output Parameters:** [Annotation type, name or ID, value when required, note, tags, timestamps, source metadata, dry-run mode, and Fulcra authentication environment settings.]
\n**Other Properties Related to Output:** [The bundled helper uses Python and uv, pins authenticated API calls to the Fulcra API host, supports dry-run writes, and treats a write as confirmed only after readback verification.]
\n\n## Skill Version(s):
\n1.0.13
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.13:agents/openai.yaml\n\ninterface:\n display_name: \"Fulcra Annotations\"\n short_description: \"Create, list, and record Fulcra annotations from agents.\"\n default_prompt: \"Create, list, or record a Fulcra annotation only when the user explicitly asks for Fulcra annotation work.\"\n\nArchive v1.0.12: 7 files, 15682 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6270b), references/api-notes.md (1589b), scripts/fulcra_annotations.py (15621b), skill-card.md (2529b), SKILL.md (15991b), _meta.json (138b)\n\nFile v1.0.12:SKILL.md\n\n---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the bundled script first. Do not hand-write curl calls unless the script is missing a required capability, because the script keeps tokens out of chat, builds the Fulcra ingest payload consistently, and performs readback verification.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` or `Asked Agent to Do Something New`. Created once with `create`.\n- **Annotation record**: one logged occurrence/value of a definition. Written with `record`.\n- **Moment annotation**: an event with no value. Use for \"this happened\" logs.\n- **Boolean/numeric/scale annotations**: metric-like records that require `--value`.\n- **Definition tags**: reusable labels stored on the annotation definition. Add them when creating the definition with repeated `create --tag`.\n- **Record tags**: labels stored on one specific record. Add them when recording with repeated `record --tag`.\n- **Tag resolution**: Fulcra stores tag IDs. The script accepts tag names or UUIDs, resolves names to IDs, and creates missing tag names automatically.\n- **Historical record**: any record whose event time is not now. Always pass `--recorded-at`.\n- **Confirmed write**: a record is not confirmed until readback finds `verified_matches >= 1`.\n\n## Safety Rules\n\n- Never print access tokens, refresh tokens, raw private Fulcra records, credential files, or direct capability URLs in chat.\n- Device auth URLs and user codes are allowed only when the intended user needs to approve Fulcra access from another device; send them only through the active trusted user channel.\n- Ask before deleting or updating an existing annotation definition.\n- For public demos, use synthetic annotation names/values unless the user explicitly approves real data.\n- Do not claim a write succeeded from HTTP status alone. Check the script result and verify readback.\n- Duration annotations are only partially supported by this skill; prefer moment/boolean/numeric/scale until Fulcra documents duration ingest shape more clearly.\n\n## Auth\n\nThe script gets auth from a trusted secret manager token when `FULCRA_ACCESS_TOKEN` is set, otherwise from the locally authenticated Fulcra CLI command configured by `FULCRA_CLI_COMMAND`.\n\nFulcra requires an authenticated account, not an API key. Accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nAuthenticate first:\n\n```bash\nuv tool run fulcra-api auth login\n```\n\nFor remote agents, keep the CLI running, surface the printed device authorization URL and code to the intended user in chat through the active trusted user channel, and wait for approval. The user can open the URL from any browser on any device. After approval, verify auth with a non-token command such as `uv tool run fulcra-api user-info`; do not paste tokens into chat.\n\nSet `FULCRA_HOME=/path/to/home` if credentials are not under the process `HOME`.\n\n## Common Commands\n\nList annotation definitions before creating a new one:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nUse `create --tag` more than once to attach multiple tags to the definition. Definition tags should be short, stable labels such as `agent`, `health`, or `research`. The script resolves tag names to Fulcra tag IDs before sending the API payload.\n\nRecord a moment annotation now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nUse `record --tag` more than once to attach tags to the individual record. If `record --tag` is omitted, the record inherits the definition tags. If `record --tag` is present, those explicit record tags are resolved to Fulcra tag IDs and sent for that record.\n\nRecord a historical moment annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\"\n```\n\nUse a full ISO-8601 timestamp with timezone for historical writes. If the user says \"yesterday at 10am\", resolve it in the user's timezone and pass the offset explicitly, for example `2026-05-15T10:00:00-04:00`. Fulcra readback may show the equivalent UTC time, such as `2026-05-15T14:00:00+00:00`.\n\nRecord by annotation ID when names are ambiguous:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\"\n```\n\nCreate a 1-5 scale annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type scale \\\n --name \"Focus\" \\\n --description \"How focused do I feel right now?\" \\\n --scale-labels \"1=Scattered,2=Low,3=Neutral,4=Focused,5=Locked In\" \\\n --default-value 3\n```\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor measurements with specialized units, inspect the live schema through the bundled helper before creating the definition and then prefer adding script support over ad hoc API calls:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw schema output into chat if it includes private account context.\n\nRecord a scale/numeric/boolean value:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" \\\n --value 4 \\\n --note \"Deep work block started well\"\n```\n\nRead back recent records for verification:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py recent \\\n --name \"Asked Agent to Do Something New\" \\\n --hours 72 \\\n --limit 20\n```\n\nUpdate definition metadata or replace definition tags only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag workflow \\\n --tag agent\n```\n\nDelete a definition only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\nDry-run any write before sending it:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Focus\" --value 4 --dry-run\n```\n\n## Workflow\n\n1. Determine the annotation type: moment, boolean, numeric, or scale. Prefer moment for \"this happened\".\n2. Decide whether tags belong on the definition, the individual record, or both.\n3. Run `list` and check whether the definition already exists.\n4. If an existing definition needs a metadata or tag change, ask for approval and use `update --id ...`; dry-run first for broad retagging.\n5. If the definition is missing and the user asked to create/log that annotation, run `create`.\n6. Record with `record --name ...` or `record --id ...`.\n7. For historical writes, always include `--recorded-at \"\"`.\n8. Trust only a successful script result with `verified_matches >= 1` for confirmed writes.\n9. If verification fails after ingest returns `204`, wait briefly and rerun `recent --id ` or `recent --name \"\" --hours `.\n10. Report the exact timestamp written and the readback timestamp. Do not include tokens, direct capability URLs, or unnecessary private record data.\n\n## Demo and Handoff Pattern\n\nFor onboarding, the first verified record should lead to a small payoff instead of a dry \"done\" message.\n\n- Offer 2-3 visual directions and ask the user to choose before generating a dashboard or artifact.\n- Keep demo files local to the workspace and avoid dumping raw HTML or raw Fulcra records into chat.\n- Use the verified annotation name, timestamp, value, and a short interpretation. Avoid exposing unrelated Fulcra data.\n- Make the next steps concrete: install/open the Context app for mobile logging, inspect data in Context Web, add another annotation, or iterate on the dashboard.\n- In public or group-chat demos, use synthetic values unless the user explicitly approved sharing real values.\n\n## Idempotent Writer Pattern\n\nFor automated or backfilled annotation pipelines, use an append-only, ledger-backed writer:\n\n1. Normalize the source event into stable fields: annotation name/id, event timestamp, source, severity/category, value/note, and any real filter dimensions.\n2. Generate a dedupe key from stable source facts. Keep this key in local state, metadata, or source bookkeeping; do not place it in the visible note.\n3. Check the local ledger before writing. Skip `verified`, retry `pending` or `failed`, and write only unseen keys.\n4. Treat ingest HTTP success as provisional. Confirm with `record` output or `recent` readback and mark the ledger `verified` only when `verified_matches >= 1`.\n5. For changed source events, avoid duplicate annotations unless the change is materially new. Prefer a follow-up annotation for escalation/resolution over rewriting history.\n\n## Tag Rules\n\n- Use definition tags for stable classification of the annotation itself, such as `health`, `agent`, `research`, or `workflow`.\n- Use record tags for context that applies only to one logged occurrence, such as `new-task`, `manual-test`, `backfill`, or `user-requested`.\n- Add definition tags with `create --tag `. Repeat `--tag` for multiple definition tags.\n- Add record tags with `record --tag `. Repeat `--tag` for multiple record tags.\n- `--tag` accepts either a Fulcra tag name or an existing tag UUID.\n- Fulcra stores tags as UUIDs. The script resolves tag names to UUIDs and creates a missing tag name automatically.\n- If `record --tag` is omitted, the record uses the definition tags.\n- If `record --tag` is provided, the explicit record tags are sent for that record.\n- Use lowercase, short, reusable tags. Prefer `new-task` over a full sentence.\n- Tags should be filter dimensions, not prose. For places, prefer actual geography such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus` over abstract tags such as `scope-town` or `scope-neighborhood`.\n- Pair place tags with category/source/severity tags when useful, for example `category-traffic`, `source-town-feed`, or `severity-advisory`.\n- Do not use tags for timestamps, detailed notes, values, people names, dedupe keys, or private context. Use `--recorded-at`, `--note`, `--value`, `--source`, and local metadata/ledger state for those.\n- Existing definitions can be retagged with `update --id ... --tag ...` after user approval; `--tag` replaces the definition tag set.\n\n## Timestamp Rules\n\n- If `--recorded-at` is omitted, the script records the annotation at the current time.\n- If the user asks for a historical or scheduled-looking time, pass `--recorded-at`.\n- Use the user's local timezone when resolving relative phrases like \"yesterday at 10am\".\n- Include the timezone offset in the timestamp. Do not pass naive local times.\n- UTC readback is expected. Compare instants, not string equality.\n\nExample: on 2026-05-16 in Eastern Time, \"yesterday at 10am\" means `2026-05-15T10:00:00-04:00`, which readback may show as `2026-05-15T14:00:00+00:00`.\n\n## Verification Rules\n\n- `record` returns `recorded_at` and `verified_matches`.\n- `verified_matches >= 1` means the script found the written record in Fulcra after ingest.\n- `uv tool run fulcra-api data-updates ` can show that annotation-related data types were processed in a time range, but it is not record-level write verification. Do not use update counts as proof that a specific annotation record was created, changed, or deleted.\n- For historical writes, use `recent --hours` with a window large enough to include the target time if a second verification is needed.\n- When inspecting readback, use only minimal fields needed for confirmation: annotation name/id, `recorded_at`, value if relevant, and note if relevant.\n\n## API Notes\n\nCore REST endpoints:\n\n- `GET /user/v1alpha1/annotation` lists annotation definitions.\n- `POST /user/v1alpha1/annotation` creates a definition.\n- `PUT /user/v1alpha1/annotation/{annotation_id}` updates a definition.\n- `DELETE /user/v1alpha1/annotation/{annotation_id}` deletes a definition.\n- `POST /ingest/v1/record` records annotation events.\n- `POST /ingest/v1/record/batch` records batches of annotation events.\n- Readback uses `/data/v1alpha1/event/MomentAnnotation` for moment/duration and `/data/v1alpha1/metric/{BooleanAnnotation|NumericAnnotation|ScaleAnnotation}` for metric annotation values.\n\nFor bulk or backfill pipelines, `data-updates` is a coarse freshness diagnostic after ingest. It supplements the local ledger and record readback; it does not replace either.\n\nFor schema details or upstream gaps, read `references/api-notes.md`.\n\nFile v1.0.12:README.md\n\n# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates, updates, and deletes annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed, or `FULCRA_ACCESS_TOKEN` supplied by a trusted secret manager.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. Set `FULCRA_CLI_COMMAND` only when you need to override the default `uv tool run fulcra-api` command.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at least `1`.\n\n## First-Run Flow\n\nFor a new user, keep the first annotation loop tight:\n\n1. Offer 2-3 concrete tracking ideas instead of asking an open-ended question.\n2. Check auth with `uv tool run fulcra-api user-info`; if needed, run `uv tool run fulcra-api auth login` and send only the device URL/code.\n3. Create 1-3 definitions, saving the returned `annotation.id`, `source_id`, and type in your working notes.\n4. Ask one direct question, record the first value with `record --id ...`, and verify `verified_matches >= 1`.\n5. Hand off with the definitions created, the timestamp written, and a concrete next step such as mobile logging, Context Web, another annotation, or a small dashboard.\n\nFor public demos or group chats, use synthetic values unless the user explicitly approves sharing real Fulcra records.\n\nCreate a numeric count annotation:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type numeric \\\n --name \"Coffee Count\" \\\n --description \"Number of coffees consumed today\" \\\n --measurement-type count \\\n --tag health \\\n --tag intake\n```\n\nFor specialized measurement units, inspect the live schema through the bundled helper before adding script support:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py measurement-schema\n```\n\nUse `measurement-schema --raw` only for local debugging. Do not paste raw private account output into chat.\n\nUpdate or delete definitions only after user approval:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py update \\\n --id \"\" \\\n --description \"Updated description\" \\\n --tag health \\\n --tag workflow\n\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py delete \\\n --id \"\"\n```\n\n## Idempotent Pipelines\n\nFor recurring imports or backfills, keep a local ledger keyed by stable source facts. Write unseen records once, retry pending/failed records, and mark a record verified only after Fulcra readback. Keep dedupe keys out of visible notes; store them in local state, metadata, or source bookkeeping.\n\n## Tags\n\nTags can apply to either the definition or an individual record.\n\nUse definition tags for stable categories that describe the annotation itself:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Medication Taken\" \\\n --tag health \\\n --tag adherence\n```\n\nUse record tags for context that only applies to one event:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Medication Taken\" \\\n --note \"Backfilled after travel\" \\\n --tag backfill \\\n --tag travel\n```\n\nUse short, reusable, lowercase tags such as `health`, `agent`, `research`, `new-task`, `manual-test`, or `backfill`. Tags should be filter dimensions. For geography, prefer actual place tags such as `town-springfield`, `village-riverside`, `neighborhood-downtown`, or `place-main-campus`, not abstract scope labels. Do not put timestamps, private notes, dedupe keys, or one-off sentences in tags.\n\n## Safety\n\n- Do not print access tokens, direct capability URLs, or private Fulcra records in chat or logs.\n- Use dry-run mode before risky writes.\n- Ask before deleting or changing an existing annotation definition.\n\nFile v1.0.12:_meta.json\n\n{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.12\",\n \"publishedAt\": 1783005578605\n}\n\nFile v1.0.12:references/api-notes.md\n\n# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n- `DELETE /user/v1alpha1/annotation/{annotation_id}`\n- `POST /user/v1alpha1/annotation/{annotation_id}/cancel_deletion`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe generic ingest endpoint is:\n\n`POST /ingest/v1/record`\n\nPayload shape:\n\n```json\n{\n \"specversion\": 1,\n \"data\": \"{\\\"note\\\":\\\"optional note\\\",\\\"value\\\":4}\",\n \"metadata\": {\n \"data_type\": \"ScaleAnnotation\",\n \"recorded_at\": \"2026-05-14T19:30:00Z\",\n \"source\": [\n \"com.example.agent\",\n \"com.fulcradynamics.annotation.\"\n ],\n \"tags\": [],\n \"content_type\": \"application/json\"\n }\n}\n```\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Current Gaps\n\nThe beta CLI currently does not expose annotation write commands or Magic Link retrieval. Prefer the bundled REST script until upstream CLI support lands.\n\nFile v1.0.12:skill-card.md\n\n## Description:
\nCreate, list, update, and record Fulcra annotations through the Fulcra Life API.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, operators, and agents use this skill to create Fulcra annotation definitions and record user-approved moments, boolean values, numeric values, and scale ratings. It is intended for workflows that need verified writeback to Fulcra Life API annotation records.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The helper can send bearer-token requests to an API host controlled by FULCRA_API_BASE.
\nMitigation: Install only in a trusted runtime and set FULCRA_API_BASE only when the endpoint is fully trusted.
\nRisk: Fulcra tokens, credential files, direct capability URLs, or private records could be exposed through chat or logs.
\nMitigation: Use trusted secret storage or local CLI authentication, never paste tokens or credential files into chat, and report only the minimal fields needed for confirmation.
\nRisk: Dry-run flows that include tags may still create missing tags remotely before returning the planned payload.
\nMitigation: Treat dry-run with tags cautiously, pre-create or verify tags where needed, and avoid using dry-run as a guarantee that no remote state changed.
\n\n\n## Reference(s):
\n- [F\n\nArchive v1.0.11: 7 files, 15407 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6270b), references/api-notes.md (1589b), scripts/fulcra_annotations.py (15621b), skill-card.md (2405b), SKILL.md (15470b), _meta.json (138b)\n\nArchive v1.0.10: 7 files, 15345 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6270b), references/api-notes.md (1589b), scripts/fulcra_annotations.py (15621b), skill-card.md (2247b), SKILL.md (15470b), _meta.json (138b)\n\nArchive v1.0.9: 7 files, 16081 bytes\n\nFiles: agents/openai.yaml (186b), README.md (6270b), references/api-notes.md (2024b), scripts/fulcra_annotations.py (18397b), skill-card.md (2444b), SKILL.md (15470b), _meta.json (137b)\n\nArchive v1.0.8: 7 files, 15724 bytes\n\nFiles: _meta.json (137b), agents/openai.yaml (186b), README.md (5878b), references/api-notes.md (2024b), scripts/fulcra_annotations.py (18397b), skill-card.md (2489b), SKILL.md (15062b)\n\nArchive v1.0.7: 7 files, 15639 bytes\n\nFiles: agents/openai.yaml (186b), README.md (5878b), references/api-notes.md (2024b), scripts/fulcra_annotations.py (18397b), skill-card.md (2206b), SKILL.md (15062b), _meta.json (137b)","readmeExcerpt":"Skill: Fulcra Annotations Owner: arc-claw-bot Summary: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/defin... Tags: latest:1.0.16 Version history: v1.0.16 | 2026-07-12T11:11:07.166Z | user Refresh fulcra-api 0.1.36 wording while restoring the clean legacy helper surface with inline readback verification. v1.0.15 ","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"uv tool run fulcra-api auth login"},{"language":"bash","snippet":"python3 skills/fulcra-annotations/scripts/fulcra_annotations.py list"},{"language":"bash","snippet":"python3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task"},{"language":"bash","snippet":"python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task"},{"language":"bash","snippet":"python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"User asked for a new annotation workflow\""},{"language":"bash","snippet":"python3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --id \"\" \\\n --note \"Logged from automation\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: fulcra-annotations\ndescription: Create, list, update, and record Fulcra annotations through the Fulcra Life API. Use when a user asks to log an annotation, create an annotation button/definition, record a moment/boolean/numeric/scale annotation, inspect annotation IDs/source IDs, or build agent workflows that write Fulcra annotation events.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"python3\",\"uv\"]},\"permissions\":[\"shell:uv-tool-run-fulcra-api\",\"network:https://api.fulcradynamics.com\",\"env:FULCRA_ACCESS_TOKEN\",\"env:FULCRA_HOME\",\"env:FULCRA_AGENT_SOURCE\"]}}\n---\n\n# Fulcra Annotations\n\nUse this skill when the user wants an agent to create, record, or verify Fulcra annotations.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. Use this skill for the write side of that loop: creating reusable annotation definitions and recording user-approved moments or values.\n\nAgents should use the bundled script first. Do not hand-write curl calls unless the script is missing a required capability, because the script keeps tokens out of chat, builds the Fulcra ingest payload consistently, and performs readback verification.\n\n## First-Run Onboarding Pattern\n\nWhen a user is new to Fulcra annotations, optimize for a quick useful loop: choose a concrete thing to track, create one or two definitions, record one real data point, verify it, and show the user what now exists.\n\n1. Start with a short, grounded prompt. Do not ask only \"what do you want to track?\"; offer 2-3 specific options based on the user's context, such as a daily focus score, coffee count, symptom check, workout effort, or a moment log for important events.\n2. Check auth only after there is a clear use case. If `uv tool run fulcra-api user-info` fails, run `uv tool run fulcra-api auth login`, keep the process alive, and send only the device URL/code through the trusted user channel.\n3. Translate the use case into 1-3 annotation definitions. Prefer the simplest type that captures the signal: `moment` for occurrences, `boolean` for yes/no, `numeric` for counts or measured quantities, and `scale` for subjective ratings.\n4. Run `list` before `create` to avoid duplicates. If creating multiple definitions, save the returned `annotation.id`, `source_id`, and type from each create result in your working notes so the next record step does not need another lookup.\n5. Ask one direct question for the first record, then call `record --id ...` with `--value` when needed. Treat success as confirmed only when `verified_matches >= 1`.\n6. For the handoff, summarize the definition names, the exact timestamp written, and one natural next action. If generating a demo artifact, use synthetic or explicitly approved real data and keep private records out of chat.\n\n## Core Concepts\n\n- **Annotation definition**: the reusable button/metric definition, such as `Focus` o"},{"path":"README.md","content":"# Fulcra Annotations\n\nCreate Fulcra annotation definitions and record annotation events from an agent workflow.\n\nFulcra gives agents and their humans scoped, secure access to read and write real-world context and shared human/agent memory: attention, events, location, calendar, health, wearables, and other streams. This skill is the write path: agents can create reusable annotation definitions and record moments, booleans, numeric values, and scale ratings after user approval.\n\n## What It Does\n\n- Lists existing Fulcra annotation definitions.\n- Creates, updates, and deletes annotation definitions, including definition-level tags.\n- Records annotation events, including historical timestamps.\n- Supports moment, boolean, numeric, and scale annotations.\n- Supports record-level tags for individual logged events.\n- Verifies writes by reading the event back after ingest.\n\n## Requirements\n\n- Python 3.11 or newer.\n- Authenticated Fulcra account for the target user. No API key is required.\n- `uv tool run fulcra-api auth login` completed, or `FULCRA_ACCESS_TOKEN` supplied by a trusted secret manager.\n\nFulcra accounts can be created through the CLI auth flow and include 5 GB of storage free forever. Users who want biometrics, location, calendar, and other mobile context can install the Context iOS app and sign in with the same account; the app uses the same free storage and is no longer subscription gated. Android is coming soon.\n\nFor remote agents, run `uv tool run fulcra-api auth login` on the agent host, keep it polling, and surface only the printed device authorization URL and user code to the intended user in chat through the active trusted user channel. The user can approve from any browser on any device. Never send access tokens or credential files.\n\nIf credentials live outside the process home, set `FULCRA_HOME` to the home directory that contains the Fulcra CLI credentials. Set `FULCRA_CLI_COMMAND` only when you need to override the default `uv tool run fulcra-api` command.\n\n## Quick Start\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py list\n```\n\nCreate a reusable moment annotation definition:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py create \\\n --type moment \\\n --name \"Asked Agent to Do Something New\" \\\n --description \"Logged when the user asks the agent to try a new category of work\" \\\n --tag agent \\\n --tag new-task\n```\n\nRecord a moment now:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --note \"User asked for a new annotation workflow\" \\\n --tag new-task\n```\n\nRecord a historical moment:\n\n```bash\npython3 skills/fulcra-annotations/scripts/fulcra_annotations.py record \\\n --name \"Asked Agent to Do Something New\" \\\n --recorded-at \"2026-05-15T10:00:00-04:00\" \\\n --note \"Backfilled from user request\" \\\n --tag backfill\n```\n\nThe script returns JSON. Treat the write as confirmed only when `verified_matches` is at l"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7bjcdhk2dyk0wc92njxshp9d80939t\",\n \"slug\": \"fulcra-annotations\",\n \"version\": \"1.0.16\",\n \"publishedAt\": 1783854667166\n}"},{"path":"references/api-notes.md","content":"# Fulcra Annotation API Notes\n\nLoaded only when schema details matter.\n\n## Definition Endpoints\n\nThe public OpenAPI document is served from:\n\n`https://api.fulcradynamics.com/openapi.json`\n\nDocumented annotation definition endpoints:\n\n- `GET /user/v1alpha1/annotation`\n- `POST /user/v1alpha1/annotation`\n- `GET /user/v1alpha1/annotation/{annotation_id}`\n- `PUT /user/v1alpha1/annotation/{annotation_id}`\n- `DELETE /user/v1alpha1/annotation/{annotation_id}`\n- `POST /user/v1alpha1/annotation/{annotation_id}/cancel_deletion`\n\nSupported definition types:\n\n- `moment`\n- `boolean`\n- `numeric`\n- `scale`\n- `duration`\n- `people`\n\n## Event Ingest\n\nThe generic ingest endpoint is:\n\n`POST /ingest/v1/record`\n\nPayload shape:\n\n```json\n{\n \"specversion\": 1,\n \"data\": \"{\\\"note\\\":\\\"optional note\\\",\\\"value\\\":4}\",\n \"metadata\": {\n \"data_type\": \"ScaleAnnotation\",\n \"recorded_at\": \"2026-05-14T19:30:00Z\",\n \"source\": [\n \"com.example.agent\",\n \"com.fulcradynamics.annotation.\"\n ],\n \"tags\": [],\n \"content_type\": \"application/json\"\n }\n}\n```\n\nObserved readback data classes:\n\n- Moment annotations: `/data/v1alpha1/event/MomentAnnotation`\n- Duration annotations: `/data/v1alpha1/event/DurationAnnotation`\n- Boolean annotations: `/data/v1alpha1/metric/BooleanAnnotation`\n- Numeric annotations: `/data/v1alpha1/metric/NumericAnnotation`\n- Scale annotations: `/data/v1alpha1/metric/ScaleAnnotation`\n\n## Current Gaps\n\nThe beta CLI currently does not expose annotation write commands or Magic Link retrieval. Prefer the bundled REST script until upstream CLI support lands."},{"path":"skill-card.md","content":"## Description:\n\nCreate, list, record, and verify Fulcra annotation definitions and events through the Fulcra Life API.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[arc-claw-bot](https://clawhub.ai/user/arc-claw-bot)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to create Fulcra annotation definitions, record approved moment or metric annotations, and verify writes through readback.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Authentication depends on local Fulcra CLI execution and account credentials.\n\nMitigation: Install only with a trusted Fulcra account, API endpoint, and CLI supply chain; prefer a pinned reviewed CLI version or vetted local binary.\n\nRisk: Broad FULCRA_CLI_COMMAND overrides could route authentication through an unintended executable.\n\nMitigation: Keep the default Fulcra CLI invocation when possible and avoid overrides unless the executable path has been reviewed.\n\nRisk: Update, delete, bulk, or backfill workflows can change existing annotation state or create many records.\n\nMitigation: Require explicit user confirmation, use dry-run mode before writes, and use a reviewed admin or ledger-backed workflow for broad changes.\n\nRisk: Fulcra records and tokens may contain private user data.\n\nMitigation: Do not print access tokens, credential files, capability URLs, or raw private records in chat or logs; share device authorization details only through the trusted user channel.\n\n## Reference(s):\n\n- [Fulcra Annotation API Notes](references/api-notes.md)\n- [Fulcra API OpenAPI document](https://api.fulcradynamics.com/openapi.json)\n- [ClawHub skill page](https://clawhub.ai/arc-claw-bot/skills/fulcra-annotations)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration, JSON]\n\n**Output Format:** [Markdown guidance with bash commands and JSON command results]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Fulcra authentication and readback verification for confirmed writes.]\n\n## Skill Version(s):\n\n1.0.16 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1769,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:26:05.113Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T06:43:48.235Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}