Update to Awaken Tax

{
  "description": "Guide to Awaken (crypto tax & portfolio) for agents — via the Awaken MCP tools when connected, or the public GraphQL API otherwise. Use for any question about transactions, portfolio, reports, accounts, 1099-DA reconciliation, diagnosing proceeds or cost-basis discrepancies, labeling, available queries/mutations, or how to authenticate and call the API. Run `/awaken setup` once after installing if using the direct GraphQL path (not needed when the Awaken MCP server is connected).",
  "included_files": [
    {
      "relative_path": "cookbook.md",
      "size_in_bytes": 62058
    }
  ],
  "name": "awaken",
  "skill_md_contents": "---\nname: awaken\ndescription: >-\n    Guide to Awaken (crypto tax & portfolio) for agents — via the Awaken\n    MCP tools when connected, or the public GraphQL API otherwise. Use for\n    any question about transactions, portfolio, reports, accounts, 1099-DA\n    reconciliation, diagnosing proceeds or cost-basis discrepancies,\n    labeling, available queries/mutations, or how to authenticate and call\n    the API. Run `/awaken setup` once after installing if using the direct\n    GraphQL path (not needed when the Awaken MCP server is connected).\n---\n\n<!--\nInstalling this skill: place this awaken/ folder at\n~/.claude/skills/awaken (or .claude/skills/awaken inside a project),\nthen run /awaken setup. On claude.ai, upload the zip under\nSettings > Capabilities > Skills instead.\n-->\n\n# Awaken\n\n## Which path to use\n\nCheck your available tools for Awaken MCP tools (names starting with\n`awaken_`, e.g. `awaken_list_transactions`).\n\n- **MCP tools present** → follow [Working through MCP](#working-through-mcp).\n  Prefer the MCP tools over direct API calls: authentication is already\n  handled by the connection, and MCP writes are grouped into sessions that\n  can be reverted in one step — raw GraphQL writes are not.\n- **No MCP tools** → follow\n  [Working through GraphQL directly](#working-through-graphql-directly).\n  It is fully self-sufficient but needs a one-time key setup\n  (`/awaken setup`). You may mention that the Awaken MCP server\n  (`claude mcp add awaken https://mcp.awaken.tax/mcp --transport http ...`,\n  full command under awaken.tax → Settings → API Keys) is a safer\n  alternative for editing, but never block on it.\n\n**If invoked as `/awaken setup`**: when MCP tools are present, no setup is\nneeded — verify the connection with a quick `awaken_get_active_client` call\nand say so. Otherwise skip straight to\n[First-time setup](#first-time-setup) and run it. If `AWAKEN_API_KEY` is\nalready set, verify it with a small live query instead, and offer to\nreplace it if verification fails.\n\n## Working through MCP\n\nAuthentication rides on the MCP connection — never ask for an API key on\nthis path. Start by calling `awaken_get_active_client` to confirm which\nclient (portfolio) you are operating on; switch with\n`awaken_set_active_client` if the user has several.\n\n### Editing safely\n\n- Write tools fail with a Read-level key; only ReadWrite keys can modify\n  data. If writes 403, say so rather than retrying.\n- Every write tool accepts an optional `sessionId`. Reuse one value (e.g.\n  `fix-basis-2025-06`) across the write calls of one logical task so the\n  batch can be reviewed with `awaken_list_edit_sessions` and reverted in\n  one step with `awaken_undo_session`. If omitted, writes made with the\n  same API key on the same UTC day share an automatic session.\n- `awaken_undo_session` defaults to a dryRun preview; pass `dryRun: false`\n  only after reviewing the preview (with the user, for anything sizable).\n- Writes mark the client for cost-basis recalculation automatically, so\n  totals can lag until the next recalculate finishes. There is no MCP\n  recalculation tool — do not go looking for one.\n- Before labeling, fetch valid values from `awaken_list_labels` and\n  `awaken_get_transaction_type_options`; never invent label ids.\n- After bulk edits, sanity-check the result with `awaken_get_tax_summary`\n  or `awaken_get_transactions_summary`.\n\n### Task → tool map\n\n| Task                              | Tools                                                                                                                                                                                                                                                                                           |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| List / filter transactions        | `awaken_list_transactions`                                                                                                                                                                                                                                                                      |\n| Period totals, yearly tax summary | `awaken_get_transactions_summary`, `awaken_get_tax_summary`                                                                                                                                                                                                                                     |\n| Valid labels & transaction types  | `awaken_list_labels`, `awaken_get_transaction_type_options`                                                                                                                                                                                                                                     |\n| Label transactions                | `awaken_label_transactions` (`awaken_split_wallet_transactions_and_label_fees` for wallet txns with fee legs)                                                                                                                                                                                   |\n| Fix a transfer's numbers          | `awaken_set_transfer_value`, `awaken_update_transfer`                                                                                                                                                                                                                                           |\n| Edit transaction fields           | `awaken_update_title`, `awaken_update_notes`, `awaken_update_transaction_hash`, `awaken_update_date`, `awaken_update_income`, `awaken_update_impermanent_loss`, `awaken_update_interest_expense`, `awaken_update_perpetual_pnl`, `awaken_update_staking_account`, `awaken_update_missing_basis` |\n| Create / reshape transactions     | `awaken_create_transaction`, `awaken_add_transfer`, `awaken_split_transaction_into_many`, `awaken_merge_transactions`, `awaken_hide_transactions`                                                                                                                                               |\n| Review & undo edits               | `awaken_list_edit_history`, `awaken_list_edit_sessions`, `awaken_undo_session`, `awaken_undo_audit_logs`                                                                                                                                                                                        |\n| Portfolio & positions             | `awaken_get_portfolio`, `awaken_get_portfolio_value`, `awaken_get_asset_position`, `awaken_list_tax_lots`                                                                                                                                                                                       |\n| NFTs                              | `awaken_list_nfts`, `awaken_set_nft_price`                                                                                                                                                                                                                                                      |\n| Performance & insights            | `awaken_get_top_pnl_assets`, `awaken_get_performance_by_chain`, `awaken_list_insights`, `awaken_get_insights_summary`                                                                                                                                                                           |\n| Accounts & assets                 | `awaken_list_accounts`, `awaken_search_assets`                                                                                                                                                                                                                                                  |\n| Investments book (SAFEs/SAFTs)    | `awaken_list_investments`, then `awaken_create_investment`, `awaken_update_investment`, `awaken_delete_investment`                                                                                                                                                                              |\n| 1099-DA reconciliation            | `awaken_list_1099da_forms`, `awaken_get_1099da_reconciliation`, `awaken_get_1099da_basis_matches`, `awaken_get_1099da_8949_preview`, then `awaken_start_1099da_form` / `awaken_generate_1099da_reports` / `awaken_list_1099da_generations`                                                      |\n| Reports & exports                 | `awaken_get_report_export`, `awaken_generate_tax_forms_bundle`, `awaken_list_taxable_events`                                                                                                                                                                                                    |\n| What shipped recently in Awaken   | `awaken_list_changelog`                                                                                                                                                                                                                                                                         |\n\nTool schemas come from the server — trust them over this table if they\ndiffer.\n\n### Splitting transactions\n\nUse `awaken_split_transaction_into_many` for every new split, including a\nsimple one-to-two split. The older `awaken_split_transaction` tool is deprecated\nand remains available only for compatibility.\n\nPass one `splits` entry per child transaction. The base keeps every visible\ntransfer omitted from those entries, and the array order is the economic\nsettlement order used for cost-basis processing. Each transfer ID must occur in\nexactly one child. A request may contain at most 20 child groups, with at most\n200 transfer IDs in each group. The operation is atomic: either every child is\ncreated or none is. Reuse one `sessionId` for the surrounding edit task so the\nwhole change can be reviewed and undone together. Split results are dirty until\nthe next recalculation, so do not validate gains or missing basis immediately\nfrom the mutation response.\n\n### Investments book\n\nThe `awaken_*_investment` tools edit the client's investment records\n(SAFEs, SAFTs, token warrants, equity — the Investments page), not ledger\ntransactions. Three ways they differ from the transaction tools:\n\n- **No undo.** Investment writes are not audit-logged, so\n  `awaken_list_edit_sessions` / `awaken_undo_session` do not cover them,\n  and `awaken_delete_investment` is a permanent hard delete that also\n  removes the record's attached documents. Confirm targets with\n  `awaken_list_investments` first, and prefer `status=cancelled` over\n  deletion.\n- **Reconcile by `referenceId`.** Company names collide (equity/token twin\n  records, multiple tranches of the same deal), so match records to an\n  external source by `referenceId` and set it on every record you create.\n- **Amounts are integer cents** in the record's `currency` (default USD),\n  capped at 2,147,483,647 cents (~$21.4M, the API's Int limit) per record.\n\n### Domain knowledge (read before nontrivial work)\n\nThe [cookbook](cookbook.md) is written with GraphQL examples, but its\ndomain sections apply on either path: staking/lending/LP positions and the\nstaking identifier (transfers in and out of positions are never\ndisposals), diagnosing missing cost basis, and the guarded 1099-DA\nreconciliation workflow. For 1099-DA specifically: diagnose with read\ntools first, and do not edit transactions, accept zero basis, or generate\nfinal forms until the user has reviewed the proposed changes and\nexplicitly approved the write.\n\n## Working through GraphQL directly\n\nAwaken exposes a single production GraphQL endpoint:\n\n```\nPOST https://api.awaken.tax/graphql\n```\n\nThis path covers the supported public API surface through the worked\nexamples in [cookbook.md](cookbook.md). There are no GraphQL subscriptions\n(the `Subscription` type in the schema is the billing entity, not a\nsubscription root). Introspection is disabled in production, so you cannot\ndiscover operations from the endpoint itself.\n\n### Finding an operation\n\nStart with [cookbook.md](cookbook.md) — it covers the full range of tasks\n(transactions, editing, missing basis, recalculation, portfolio, reports,\naccounts, API keys) with verified examples, and most questions are a\nvariation of one of them. It is organized by task; grep for a keyword or\noperation name first.\n\nFor anything beyond the cookbook (only possible inside the Awaken repo):\nthe full schema is nexus-generated into `schema.graphql` at the repo root —\ngrep it for an operation name or keyword, then read the surrounding lines\nfor the signature and types. For resolver behavior beyond the signature,\nopen the resolver source under `server/src/modules/<module>/graphql/`\n(e.g. `getClientTransactions` lives in\n`server/src/modules/ledger/graphql/queries/`). Note that `schema.graphql`\nincludes internal staff-only operations; anything gated by an admin check\nin its resolver will 403 for client API keys.\n\n### Authentication\n\nRequests authenticate one of two ways:\n\n- **Firebase bearer token** (the web app): `Authorization: Bearer <firebase-jwt>`.\n- **Client API key** (integrations): keys start with `awaken_` and are sent\n  as `x-api-key: <key>` or `Authorization: ApiKey <key>`. Keys are created\n  in the web app under Settings → API Keys, are scoped to one client, and\n  carry a permission level of `Read` or `ReadWrite`. Read-level keys can\n  only run queries.\n\nMost operations take a `clientId` argument and enforce that the caller has a\nmembership on that client (`ClientPermissionService`); a user can belong to\nseveral clients (`getMyClients`, `getMyActiveClient`).\n\n#### Calling the API with an API key\n\nNever hardcode or echo a raw key. Before any live API call, check for the\nkey with `test -n \"$AWAKEN_API_KEY\"` (do not print it), and pass it as\n`-H \"x-api-key: $AWAKEN_API_KEY\"` so the raw value never appears in the\ncommand line or transcript.\n\n#### First-time setup\n\nIf `AWAKEN_API_KEY` is not set, walk the user through this once:\n\n1. Tell them to create a key at **awaken.tax → Settings → API Keys**\n   (choose `Read` unless they need to modify data; the raw key is shown\n   once, at creation). Keys expire — 90 days by default, up to a year if\n   they set a date — so a long-lived integration needs a rotation plan.\n2. Have them paste the key, then persist it for future sessions —\n   offer both options and let them pick:\n    - **Shell profile** (works for all terminal tools):\n      append `export AWAKEN_API_KEY=\"awaken_...\"` to their profile\n      (`~/.zshrc`, or `set -Ux AWAKEN_API_KEY awaken_...` for fish).\n    - **Claude Code only**: add it to the `env` block of\n      `~/.claude/settings.json`:\n      `{\"env\": {\"AWAKEN_API_KEY\": \"awaken_...\"}}`.\n3. Discover the client ID — the user should never have to find this\n   manually. Every key is scoped to exactly one client (any other\n   `clientId` returns a 403). Query `getMyClients { id name }` with the\n   key; if it returns one client, that's the one. If it returns several\n   (the key's creator belongs to multiple clients), probe each id with a\n   cheap query (`getClientTransactions(clientId: ..., limit: 1)`) — the\n   key's client is the only one that won't 403. Persist it next to the\n   key as `AWAKEN_CLIENT_ID`, using the same mechanism chosen in step 2.\n4. Confirm setup by running a small query (e.g. `getClientTransactions`\n   with `clientId: $AWAKEN_CLIENT_ID, limit: 1`) and reporting whether\n   it authenticated.\n\nIn later sessions, use `$AWAKEN_CLIENT_ID` for every `clientId` argument\nwithout asking; if it is unset but `AWAKEN_API_KEY` exists, re-run the\ndiscovery in step 3 and offer to persist the result.\n\nIf a call fails with `extensions.code: \"UNAUTHENTICATED\"` (HTTP 401),\nthe key is missing, invalid, expired, or revoked — don't retry; direct\nthe user to Settings → API Keys for a new key. A `\"403\"` (or\n`\"FORBIDDEN\"`) code means the key is valid but not allowed here: either\nthe `clientId` isn't the key's client (expected while probing in step 3 —\njust try the next id) or a `Read` key attempted a mutation (switch to a\n`ReadWrite` key). If **every** client from `getMyClients` 403s, the key\nis likely scoped to a client outside the creator's visible memberships —\nconfirm the intended client id with the user before concluding the key is\nbad; re-create it from the right workspace only if none can be reached.\n\n### Common use cases\n\n[cookbook.md](cookbook.md) has verified, ready-to-run examples for the\nfrequent tasks: listing/filtering transactions, editing and labeling them,\nfinding and fixing missing cost basis, staking/lending/LP positions and\nstaking identifiers, recalculating, portfolio balances and tax lots, NFT\nvalue overrides, reconciling 1099-DA forms, identifying the transactions\nbehind proceeds/basis discrepancies, exporting tax reports, tax-loss\nharvesting, adding wallet/exchange accounts, and managing API keys.\nStart there before composing a query from scratch.\n\nFor 1099-DA work, follow the cookbook's guarded\n**Reconcile a 1099-DA** workflow. Diagnose with read queries first. Do not\nedit transactions, accept zero basis, change report rows, or generate final\nforms until the user has reviewed the proposed changes and explicitly\napproved the write.\n\n### Conventions\n\n- **One root field per request** — the server rejects operations with more\n  than one root selection. Send separate requests instead of batching.\n- **Pagination** is offset-style via `page` and `limit` args (`limit` ≤ 500\n  on transaction queries); list responses that paginate usually return a\n  wrapper type with a `total` count.\n- **Dates** use the custom `Date` scalar; arbitrary payloads use the `JSON`\n  scalar.\n- **Money** fields suffixed `Cents` are integer cents (often paired with\n  a display-ready `...Formatted` string) — but mutation inputs named\n  `fiatValue`/`basisFiatValue` are **dollar floats** (`1837.69`). Mixing the\n  two up is a silent 100× error. Asset quantities are floats. For gains,\n  prefer `capGainsSumSigned` (signed gain/loss in **integer cents**, returned\n  as a string, e.g. `-183769` for -$1,837.69 — divide by 100 for dollars) over\n  `capGainsSum`, which is the **unsigned absolute value** and drops the\n  gain-vs-loss sign.\n- **Errors** come back as standard GraphQL errors; check `extensions.code`:\n  `\"UNAUTHENTICATED\"` (with HTTP 401) for a missing/invalid/expired/revoked\n  key; `\"403\"` or `\"FORBIDDEN\"` (treat as equivalent) for permission\n  failures (key scoped to another client, or a Read key running a\n  mutation); `\"ROOT_SELECTION_LIMIT_EXCEEDED\"` for more than one root\n  field; `\"BAD_USER_INPUT\"` for malformed arguments. Errors thrown without\n  an explicit code surface as `\"INTERNAL_SERVER_ERROR\"`.\n- **DeFi positions are virtual accounts** keyed by a _staking identifier_\n  (`stakingAccountIdentifier`), each holding one pooled basis queue per asset.\n  Transfers to/from them are internal moves — never disposals — and only the\n  staking/LP labels honor the identifier. Anything a withdrawal can't cover\n  from the queue becomes reward income at market value. See the cookbook's\n  staking-positions section before hand-building position transactions.\n- Many mutations that touch ledger data mark the client dirty and take\n  effect fully after the next recalculate — trigger one with the\n  `rerunGraph` mutation and poll `getActiveRecalculateJob` until it\n  returns `null`.\n"
}