docs!: refresh per-SDK READMEs + llms-full.txt for put/get convention#126
Merged
Conversation
2 tasks
Nic-dorman
added a commit
that referenced
this pull request
May 21, 2026
These two files are pure documentation of the wire/SDK surface; the antd daemon never loads openapi.yaml at runtime, and llms-full.txt is the consolidated LLM-targeted reference. Editing either should be treated the same as a README typo fix -- no Rust compile cycle adds signal. Surfaced today when a docs polish PR (#126) extended antd/openapi.yaml to document POST /v1/chunks/prepare and /v1/chunks/finalize. Because openapi.yaml sits under antd/** but isn't .md, the existing `!**/*.md` negation didn't catch it and CI triggered a Rust build that then surfaced an unrelated rustfmt drift in an upstream PR. Adds the two paths as additional negations alongside `!**/*.md`. No behavior change for any code-touching PR. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nic-dorman
force-pushed
the
nic/v2-340-file-upload-private
branch
from
cc9cea2 to
7e3d414
Compare
…return types, fix Quick Start .cost reads Follow-up to 4935d8a. The earlier polish caught the put/get renames but missed the *additions* introduced by V2-340 plus the return-type rename on DataPutResult / DataPutPublicResult. Per-SDK README changes across all 14 non-antd-go SDKs: - Files API tables now list both private (file_put / file_get) and public (file_put_public / file_get_public) variants. Private = caller-held DataMap (NOT stored on-network); public = DataMap stored on-network at the returned address. - Quick Start snippets stop reading result.cost on DataPutPublicResult. The field no longer exists (DataPutPublicResult has address, chunks_stored, payment_mode_used); examples now show chunks_stored instead. Same bug class as antd-mcp fixed. - Data + Files signatures show the payment_mode kwarg/parameter that all put and cost methods accept. - Return types corrected: DataPutResult / DataPutPublicResult / FilePutResult / FilePutPublicResult instead of the stale PutResult. - Models tables (where present — py, csharp, js, zig memory-notes) list the new typed results and PutResult is annotated as chunk_put only. antd-go README is updated in #116 directly and already had this content on its branch; no change here. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The JS/TS, Python, C#, Kotlin, Swift, Go, Java, Rust, C++, Ruby, PHP, Dart, Lua, Elixir, and Zig SDK signature blocks were still listing the pre-V2-340 shape: stale PutResult return type, no payment_mode parameter, and no private file_put / file_get entries. Each block now: - Lists the correct return types: DataPutResult / DataPutPublicResult / FilePutResult / FilePutPublicResult. PutResult remains only on chunk_put (the wire shape that still uses Cost + Address). - Threads payment_mode through every put/cost signature in the language-idiomatic shape (kwarg, struct opt, named arg, etc.). - Adds the file_put / file_get (private) entries V2-340 introduced -- the daemon and every SDK already expose them, only the docs were stale. Drops the misleading "address is the data_map" comments now that the new typed results expose .data_map directly on private put results. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…efresh MCP mapping Three drifts surfaced by the v1.0 surface-area sweep: 1. llms-full.txt still documented POST /v1/dirs/upload/public and /v1/dirs/download/public. PR #95 removed the dir surface from the daemon + protos + every SDK + per-SDK READMEs but missed llms-full.txt's REST routes section. The phantom is now gone. 2. /v1/chunks/prepare and /v1/chunks/finalize were never documented. The daemon routes them (antd/src/rest/mod.rs), every SDK exposes them (prepare_chunk_upload / finalize_chunk_upload), and the external-signer examples use them, but they appeared in neither llms-full.txt's REST section nor antd/openapi.yaml. Both gaps are closed: llms-full.txt has full request/response shapes (including the already_stored:true no-payment-needed path), and openapi.yaml has matching PrepareChunkRequest / PrepareChunkResponse / FinalizeChunkRequest / FinalizeChunkResponse schemas. 3. The MCP tool mapping was stale for the upload_file / download_file rows after antd-mcp #127 added the private flag to both tools. The table now matches #127's actual signatures and explains how the address field round-trips between public and private branches. 4. Adds a new "External Signer SDK Methods" section between the per-SDK signature blocks and the MCP mapping. Cross-language reference for prepare_data_upload / prepare_upload / prepare_upload_public / prepare_chunk_upload and the matching finalize_* / finalize_merkle_upload / finalize_chunk_upload methods, with a table mapping each SDK method to its REST route and finalize counterpart. All 15 SDKs expose these. EventService is out of scope: it still exists in proto + daemon + docs, consistent with each other. Whether to remove it remains a separate v1.0 decision. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Nic-dorman
force-pushed
the
nic/v1-docs-polish
branch
from
a7a5369 to
57e1e5d
Compare
Nic-dorman
added a commit
that referenced
this pull request
May 21, 2026
Cuts v0.8.0 atop v0.7.1. Substantial breaking-change roll-up of the put/get rename, the private-file PUT/GET gap close, and several minor surface cleanups -- bundled here so the v1.0 cut can ship stable on top. ## Breaking (antd daemon) - feat(antd)!: bind to 127.0.0.1 by default on REST and gRPC (#107). Previously bound 0.0.0.0; use --bind-rest / --bind-grpc to override. - chore: remove dead graph_entry surface from antd proto + 5 SDKs (#92). GraphService and its 4 RPCs are gone; REST mounts dropped. - chore: remove dir_upload_public / dir_download_public surface (#95). Use file_put_public on a directory path instead; the daemon recurses. - feat(antd)!: normalize put/get convention + close private-file PUT and GET gaps (#115). Method renames across proto + REST + SDKs: data_put_private -> data_put data_get_private -> data_get file_upload_public -> file_put_public file_download_public -> file_get_public New: file_put / file_get for the private file path (previously only the public variant existed). New typed results: DataPutResult, DataPutPublicResult, FilePutResult, FilePutPublicResult; PutResult is now annotated as chunk_put only. ## Additive - feat(antd): honor payment_mode on gRPC put/cost paths and REST cost endpoints (#114). Optional kwarg threaded through every put/cost signature; empty/omitted maps to "auto" so older clients keep working. - feat: external-signer public uploads + single-chunk prepare/finalize across 15 SDKs (#90). - docs+spec: openapi.yaml refreshed for the v1.0 surface, including POST /v1/chunks/prepare and /v1/chunks/finalize for single-chunk external-signer publish (#126). ## SDK fan-out (PaymentMode + put/get convention, all 15) #116 antd-go, #117 antd-py/ruby/elixir, #118 antd-rust, #119 antd-csharp, #120 antd-java, #121 antd-swift, #122 antd-dart, #123 antd-kotlin, #124 antd-cpp, #125 antd-js/php/zig/lua, #127 antd-mcp. ## SDK example + build fixes - fix(antd-go): make 03-files example self-contained and runnable (#91) - fix(examples): make 04-files runnable across cpp/rust/elixir/lua/php/ruby/zig (#93) - fix(examples): runnable dart 04_files + java Example03Files; add java Example03Chunks (#94) - feat: gRPC transport example for antd-py and antd-rust (#113) - feat(antd-py): 07_external_signer example + ant-dev dispatcher entry (#98) - feat(antd-js): 07-external-signer example + antd-py empty-payments fix (#99) - feat(rust/go): 07-external-signer examples (#100) - feat(antd-csharp): 07_external_signer example (#101) - feat(antd-java): 07_external_signer example (#102) - feat(antd-kotlin): 07_external_signer example (#103) - feat(antd-dart): 07_external_signer example (#104) - feat(antd-ruby): 07_external_signer example (#105) - feat(antd-php): 07_external_signer example (#106) - chore(antd-kotlin): drop stale GraphDescendant from local proto copy (#108) ## Docs / infra - docs: external-signer flow reference + ABI + python smoke test (#97) - docs: add SECURITY.md with threat model and disclosure policy (#109) - docs!: refresh per-SDK READMEs + llms-full.txt + openapi.yaml for v1.0 surface (#126) - ci: add Go lint + test + vuln scanning for antd-go (#112) - ci: extend antd-rust to sibling-repo parity (fmt + clippy + audit + doc) (#111) - ci: skip antd/openapi.yaml and llms-full.txt from triggering CI (#128) - chore(scripts): add full-stack + integration sweep helpers (#96) - fix(antd-rust): regenerate Cargo.lock to unbreak --locked CI (#110) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Consolidating-polish pass after the per-SDK fan-out (#116..#125). Top-level docs and SDK API reference tables now reflect the post-v1.0 naming.
What changed
data_put_private→data_put,data_get_private→data_getfile_upload_public→file_put_public,file_download_public→file_get_publicFileUploadResult→FilePutPublicResultllms-full.txt— the canonical multi-SDK reference:POST /v1/data/private+GET /v1/data/private→POST /v1/data+POST /v1/data/get; added newPOST /v1/files+POST /v1/files/get; renamed/v1/files/upload/public→/v1/files/publicand/v1/files/download/public→/v1/files/public/get.DataService.{Put,Get,Cost}+FileService.{Put,Get,PutPublic,GetPublic,Cost}withpayment_modethreaded; "(wasX)" tail-notes documenting each rename for grep-discoverability.PutResult(nowchunk_put-only) intoDataPutResult,DataPutPublicResult,FilePutResult,FilePutPublicResult; called outHealthStatusdiagnostic fields.payment_modenote to list all four put endpoints + the matching cost endpoints.Test plan
git statusclean (only the 15 docs files + llms-full.txt touched).grep -E "(data_put_private|dataPutPrivate|fileUploadPublic|fileDownloadPublic|file_upload_public|file_download_public|FileUploadResult)"returns no hits in any SDK README.grep -E "(/v1/data/private|/v1/files/upload|/v1/files/download)"returns no hits inllms-full.txt(the renamed routes only survive as(was X)tail-notes inside the gRPC stub lines).🤖 Generated with Claude Code