Claude docs pass 1

[LefterisJP]

** DO NOT MERG YET***

The query was

Task: Improve rotki documentation based on real user churn feedback

Context

You are working on the rotki codebase (https://github.com/rotki/rotki) — an open-source, local-first crypto portfolio tracker and tax accounting tool. A paying user just cancelled their subscription and provided detailed UX/documentation feedback. Your job is to use this feedback to concretely improve the documentation (and flag any code-level UX issues that documentation alone cannot fix). You have checked out the documentation repository. Ask if there is anything you don't understand on what you need to do.

User Feedback (verbatim)

The user's primary use case was tax accounting and DeFi profit-and-loss calculation. Their key pain points:

1. Onboarding friction — finding the right entry point

"When I was first onboarding, it took me quite a while to realize 'Profit and Loss Report' and 'History' are the two main tabs I am looking for. Their names don't hit the 'tax' keyword, and the sidebar has too many options to browse. I downloaded, installed, and pushed myself to open Rotki multiple times before I finally 'got it' and understood what buttons to hit."

2. Onboarding friction — understanding event types and subtypes

"Once I generated PnL reports but hit unexpected numbers, I started looking into individual transactions in History. I was met with a huge list of event type and subtype options. I went to the docs first but don't remember them having sufficient detail to explain what each type does. I then looked through accounting rules — slightly more helpful (shows e.g. what's taxable) but I was confused by options like 'Count cost basis PnL', and the accounting treatments 'Swap' and 'Basis Transfer'. I ended up cloning Rotki's repo, asking AI what each option means, and writing down a personal note page."

3. Lacking custom cost basis

"I moved from a no-tax country to a with-tax country and started using Rotki then. I don't have access to certain old transaction records (e.g. FTX). For tax purposes I just need existing assets to be cost-based at market prices on country entry date. A simple solution: let users define custom cost basis for specific amounts of assets."

4. Lacking custom counterparty / smart contract for accounting rules

"Without support for defining custom counterparty / smart contract in accounting rules, all transactions not automatically picked up require manual edits — labor-intensive and error-prone."

Your Task

Work through the following steps:

Step 1: Explore and understand

1. Read the existing rotki documentation structure (likely under /docs or similar). Map what currently exists for: tax workflows, event types/subtypes, accounting rules, cost basis handling, custom counterparties.
2. Read the relevant codebase areas to understand the actual behavior of:
   • Event types and subtypes (find the enum/definitions)
   • Accounting rule options including "Count cost basis PnL", "Swap" treatment, "Basis Transfer" treatment
   • How counterparties are currently defined and whether custom ones are possible
   • How cost basis is currently computed and whether any override mechanism exists

Step 2: Identify documentation gaps

For each of the user's four pain points, produce a written gap analysis:

• What does the documentation currently say (if anything)?
• What is missing or unclear?
• What would a user in this situation actually need to read?

Step 3: Improve the documentation

Make concrete edits to the docs to address the gaps. Specifically:

A) A clear "tax workflow" entry point in the docs. A top-level page (or prominent section) titled something like "Using rotki for tax accounting" that walks a new user from install → import data → reconcile → generate PnL report. This page should explicitly mention that "Profit and Loss Report" and "History" are the two key tabs, and link to deeper docs from there.

B) A complete reference for event types and subtypes. Every event type and subtype should have:

• A plain-language explanation of what it represents
• A concrete example
• Its default tax treatment
• Common cases where a user might want to recategorize

Pull the canonical list from the codebase — do not invent types.

C) A clear explanation of accounting rule options. Specifically the ones the user named: "Count cost basis PnL", "Swap" treatment, "Basis Transfer" treatment. Each needs a plain-language definition, why a user would toggle it, and a worked example.

D) Document the current behavior around cost basis and custom counterparties — even if the feature gaps exist, the docs should clearly state what is and isn't currently supported, so users don't waste time looking for features that don't exist.

Step 4: Flag what docs cannot fix

Some of this feedback is about missing features, not missing docs. Produce a separate section at the end of your work titled "Feature gaps surfaced by this feedback" listing:

• Custom cost basis for assets at a specific date (for users moving tax jurisdictions)
• Custom counterparty / smart contract definitions for accounting rules
• Any other code-level UX issues you noticed (e.g. sidebar information architecture, naming of "Profit and Loss Report" vs something more tax-keyword-friendly)

For each, suggest whether an existing GitHub issue likely covers it (search the repo's issue tracker if possible) or whether a new issue should be opened.

Constraints

• Do not invent behavior. If you're unsure how something works, read the code or flag it as needing clarification rather than guessing.
• Match the existing documentation style and tone.
• Prefer concrete examples over abstract explanations — this user explicitly said the existing docs lacked sufficient detail.
• Assume the reader is a technically competent crypto user but NOT a rotki expert and NOT an accountant.

Deliverables

1. A summary of the documentation changes you made (file paths + brief description of each change)
2. The actual doc edits as a PR-ready set of changes
3. The "Feature gaps" section flagging what needs code work
4. Any questions or uncertainties that need a human (Lefteris) to clarify before merging

---

It came back with this PR and

 Deliverable 1: Summary of Documentation Changes                                                                                                                                                                                                                               
                                                                                                                                                                                                                                                                                
  New files created                                                                                                                                                                                                                                                             
                                                                                                                                                                                                                                                                                
  ┌──────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐  
  │               File               │                                                                                                              Description                                                                                                              │
  ├──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤  
  │ usage-guides/tax-accounting.md   │ Tax Accounting Guide — A step-by-step walkthrough for new users who want to do their crypto taxes. Covers the entire workflow from connecting data sources → configuring accounting settings → reviewing history events → generating  │
  │                                  │ PnL report → exporting. Explicitly calls out "Profit and Loss Report" and "History Events" as the two key tabs. Includes a troubleshooting table and a "what rotki does NOT support" section.                                         │
  ├──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤  
  │ usage-guides/event-types.md      │ Event Types & Subtypes Reference — Complete reference for every event type (Trade, Deposit, Withdrawal, Spend, Receive, Transfer, Staking, Migration, Renew, Informational) and their subtypes. Each has a plain-language             │  
  │                                  │ explanation, concrete example, default tax treatment, and guidance on when to recategorize. Includes a quick-reference table and entry types explanation.                                                                             │  
  ├──────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤  
  │ usage-guides/accounting-rules.md │ Accounting Rule Options Explained — Detailed explanation of every accounting setting with worked examples. Specifically explains "Count cost basis PnL", "Swap" treatment, and "Basis Transfer" treatment — the three options the     │  
  │                                  │ churned user found confusing. Also covers cost basis methods (FIFO/LIFO/HIFO/ACB), crypto-to-crypto trades, tax-free periods, and custom rule limitations.                                                                            │  
  └──────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

  Modified files                                                                                                                                                                                                                                                                
                                                                                                                                                                                                                                                                                
  ┌───────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐                                             
  │               File                │                                                                                          Change                                                                                           │                                             
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ .vitepress/config.mts             │ Added "Tax Accounting Guide", "Event Types & Subtypes", and "Accounting Rule Options" to the sidebar navigation. Tax guide is placed right after the Introduction for maximum visibility. │                                             
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ index.md                          │ Added a prominent callout: "Looking to do your crypto taxes?" linking to the tax accounting guide.                                                                                        │                                             
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ usage-guides/index.md             │ Added a tip box linking to the tax accounting guide for users landing on the usage guides intro.                                                                                          │                                             
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ usage-guides/pnl.md               │ Added a tip box at the top directing new users to the tax accounting guide.                                                                                                               │                                           
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ usage-guides/historical-events.md │ Added a tip box at the top linking to the event types reference.                                                                                                                          │                                             
  ├───────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤                                             
  │ usage-guides/customization.md     │ Added a tip box in the Accounting Settings section linking to the accounting rules explanation page.                                                                                      │                                             
  └───────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘

Deliverable 2: Gap Analysis (by pain point)

Pain Point 1: Finding the right entry point

• What docs said: The landing page linked to Installation Guide → Usage Guide. No mention of "tax" anywhere in navigation or landing page.
• What was missing: A clear "start here for taxes" entry point. The words "tax", "PnL", and "Profit and Loss Report" were buried under generic "Usage Guides".
• What we added: Tax Accounting Guide as the 2nd item in Usage Guides sidebar; callouts on landing page and introduction page.

Pain Point 2: Understanding event types and subtypes

• What docs said: historical-events.md had a "Common customization" section (lines 266-283) listing some event type/subtype combinations as brief bullet points. No explanations of what they mean, no examples, no tax treatment info.
• What was missing: A reference that explains each type/subtype with plain language, examples, and default tax behavior. The existing docs assumed users already understood the taxonomy.
• What we added: Complete event-types.md reference page with tables for every type/subtype.

Pain Point 3: Accounting rule confusion

• What docs said: customization.md had settings like "Calculate Past Cost Basis" with one-line descriptions. The developer guide mentioned count_cost_basis_pnl and TxMultitakeTreatment but these are in developer docs, not user docs. "Swap" and "Basis Transfer"
  treatments were not explained for users at all.
• What was missing: User-facing explanations of what "Count cost basis PnL", "Swap" treatment, and "Basis Transfer" treatment actually mean, with worked examples.
• What we added: Complete accounting-rules.md page with detailed explanations and examples for every setting.

Pain Point 4: Cost basis and counterparty limitations

• What docs said: Nothing about these limitations. Users would search the docs and find nothing, wasting time.
• What we added: Explicit "What rotki currently does NOT support" section in the tax guide documenting both limitations clearly.

---

Deliverable 3: Feature Gaps Surfaced by This Feedback

1. Custom cost basis for assets at a specific date

Problem: Users moving from a no-tax to a with-tax country need to set cost basis at market prices on their country entry date. Users who lost access to exchange records (e.g., FTX) also need this.

Current workaround: Add manual "buy" trades at the desired price and date. This is tedious and error-prone for many assets.

Suggested feature: Allow users to define a custom cost basis for a specific amount of a specific asset at a specific date, without needing to create a fake trade.

Existing issues: Search the rotki GitHub issues for "custom cost basis" or "cost basis override". This is likely a new feature request if not already filed.

2. Custom counterparty / smart contract for accounting rules

Problem: Accounting rules can be scoped to a counterparty, but only rotki-recognized protocol identifiers (e.g., "uniswap-v3", "aave"). Users interacting with protocols not yet decoded by rotki must manually edit each individual transaction.

Suggested feature: Allow users to define custom counterparty labels for arbitrary smart contract addresses, and use those labels in accounting rules.

Existing issues: Search for "custom counterparty" or "custom protocol" in the rotki issue tracker.

3. Sidebar information architecture / naming

Problem: "Profit and Loss Report" doesn't contain the word "tax" anywhere. Users searching for tax-related features don't immediately find it. The sidebar has many items with no clear grouping for the tax workflow.

Suggested improvement: Consider renaming to "Tax / PnL Report" or adding a "Tax Reporting" section/group in the sidebar that groups History Events, PnL Report, and Accounting Settings together. This is a frontend UX change, not just docs.