docs: add "safe" tag to V2 API documentation (#13051)

* docs: initial copy of https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658

* docs: add CLAUDE.md with context about V2 API documentation work

* docs: clean up formatting in V2 API documentation

* docs: added table of contents
This makes it easier to see what content sections are being changed/added in future diffs.

* docs: add safe tag documentation with 200 epoch distance\n\nThis adds:\n- Safe tag to TipSetSelector options\n- Documentation about 200 epochs behind head placement\n- Updated comprehensive table of contents to include new sections

* docs: update based on changes/suggestions from Gemini 2.5 Pro Preview 03-25

* docs: added status update and minor CLAUDE.md update

* docs: fixed incorrect statement and pointed to safe constant investigation tracking item

* docs: fixing GoDoc for SafeHeightDistance

* docs: update api-v2-experimental.md based on PR feedback

- Removed bad recommendations for handling when need consistent state
- Fixed mermaid diagram
- Made clear this doc isn't the permanent home

* chore: cleanup
Fixed formatting errors.
Added docs about the table of contents.

* chore: fix go fmt issues in comment formatting

Author: BigLep

build/buildconstants/params_shared_vals.go

@@ -104,7 +104,17 @@ const MinimumBaseFee int64 = 100
 const PackingEfficiencyNum int64 = 4
 const PackingEfficiencyDenom int64 = 5
 
-// SafeHeightDistance is the distance from the current head that we call "safe" for the purpose of
-// assuming finality when relying on EC. It's not a substitute for ChainFinality, but a compromise
-// where it's acceptable to have a nonzero margin of error in the finality assumption.
+// SafeHeightDistance is the distance from the latest tipset, i.e. heaviest, that
+// is considered to be safe from re-orgs at an increasingly diminishing
+// probability.
+//
+// This is used to determine the safe tipset when using the "safe" tag in
+// TipSetSelector or via Eth JSON-RPC APIs. Note that "safe" doesn't guarantee
+// finality, but rather a high probability of not being reverted. For guaranteed
+// finality, use the "finalized" tag.
+//
+// This constant is experimental and may change in the future.
+// Discussion on this current value and a tracking item to document the
+// probabilistic impact of various values is in
+// https://github.com/filecoin-project/go-f3/issues/944
 const SafeHeightDistance abi.ChainEpoch = 200

documentation/en/api-experimental-user-facing-v2-docs/CLAUDE.md

@@ -0,0 +1,35 @@
+# V2 API Documentation Context
+
+## Project Overview
+This directory contains the experimental user-facing documentation for Filecoin's V2 API. The purpose of this work is to maintain the documentation in source control for easier team review before publishing to external platforms like Notion.
+
+## Source Information
+- Original source: https://filoznotebook.notion.site/Filecoin-V2-APIs-1d0dc41950c1808b914de5966d501658
+- This documentation describes experimental V2 APIs that are subject to change
+
+## Workflow
+1. (If this hasn't already been don) Copy updates from Notion into this repository
+2. Make changes, likely using Claude Code by pointing to to local changes or changes in a PR.
+2. Regenerate the table of contents if you've added or modified sections
+3. Submit changes for team review via pull request
+4. After approval, publish updated content back to Notion
+
+**Important**: Always regenerate the table of contents before committing changes to ensure it accurately reflects the document structure. The table of contents is comprehensive and includes all sections of the document, helping readers navigate the content.  It also helps give an overview in the diff of what content is being added/changed and where in the document.  
+
+## Key Files
+- `api-v2-experimental.md`: The main user facing documentation file that is copied to Notion.
+- Related code: `api/v2api/full.go` (API implementation)
+- Related code: `chain/types/tipset_selector.go` (Key types)
+- Generated docs: `documentation/en/api-v2-unstable-methods.md`
+
+## Commands
+
+### Regenerating the Table of Contents
+For Claude to regenerate the table of contents:
+1. Extract all headers from the document using grep:
+```bash
+grep -n '^#\|^##\|^###\|^####' api-v2-experimental.md
+```
+2. Use this information to update the Table of Contents section, ensuring all headers are properly nested according to their level and linked.
+
+Humans in their IDE can use [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one).