diff --git a/component-registry.yml b/component-registry.yml index f644e38..7641568 100644 --- a/component-registry.yml +++ b/component-registry.yml @@ -1,5 +1,5 @@ # Component Registry — Autonomi Developer Documentation -# Maps components within each repo to the documentation pages they feed. +# Maps components within each repo to the documentation pages and skills they feed. # See CLAUDE.md for how agents use this during writing and auditing. # See repo-registry.yml for repo-level scope and behaviour. @@ -31,6 +31,8 @@ components: - sdk/reference/daemon-command-reference.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md openapi: repo: ant-sdk @@ -40,6 +42,8 @@ components: - rest-api feeds_pages: - sdk/reference/rest-api.md + feeds_skills: + - skills/autonomi-developer/SKILL.md proto: repo: ant-sdk @@ -49,6 +53,8 @@ components: - grpc feeds_pages: - sdk/reference/grpc-services.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-dev: repo: ant-sdk @@ -62,6 +68,8 @@ components: - guides/overview.md - guides/set-up-a-local-network.md - guides/test-your-application.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-mcp: repo: ant-sdk @@ -76,6 +84,8 @@ components: - mcp/use-the-autonomi-mcp-server.md - mcp/mcp-server-reference.md - sdk/reference/overview.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-rust: repo: ant-sdk @@ -86,6 +96,8 @@ components: feeds_pages: - sdk/reference/language-bindings/overview.md - sdk/reference/language-bindings/rust.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-py: repo: ant-sdk @@ -96,6 +108,8 @@ components: feeds_pages: - sdk/reference/language-bindings/overview.md - sdk/reference/language-bindings/python.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-js: repo: ant-sdk @@ -107,6 +121,8 @@ components: - sdk/reference/language-bindings/overview.md - sdk/reference/language-bindings/javascript.md - sdk/reference/language-bindings/typescript.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-go: repo: ant-sdk @@ -117,6 +133,8 @@ components: feeds_pages: - sdk/reference/language-bindings/overview.md - sdk/reference/language-bindings/go.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-java: repo: ant-sdk @@ -126,6 +144,8 @@ components: - java-binding feeds_pages: - sdk/reference/language-bindings/java.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-csharp: repo: ant-sdk @@ -135,6 +155,8 @@ components: - csharp-binding feeds_pages: - sdk/reference/language-bindings/csharp.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-kotlin: repo: ant-sdk @@ -144,6 +166,8 @@ components: - kotlin-binding feeds_pages: - sdk/reference/language-bindings/kotlin.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-swift: repo: ant-sdk @@ -153,6 +177,8 @@ components: - swift-binding feeds_pages: - sdk/reference/language-bindings/swift.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-ruby: repo: ant-sdk @@ -162,6 +188,8 @@ components: - ruby-binding feeds_pages: - sdk/reference/language-bindings/ruby.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-php: repo: ant-sdk @@ -171,6 +199,8 @@ components: - php-binding feeds_pages: - sdk/reference/language-bindings/php.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-cpp: repo: ant-sdk @@ -180,6 +210,8 @@ components: - cpp-binding feeds_pages: - sdk/reference/language-bindings/cpp.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-dart: repo: ant-sdk @@ -189,6 +221,8 @@ components: - dart-binding feeds_pages: - sdk/reference/language-bindings/dart.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-zig: repo: ant-sdk @@ -198,6 +232,8 @@ components: - zig-binding feeds_pages: - sdk/reference/language-bindings/zig.md + feeds_skills: + - skills/autonomi-developer/SKILL.md antd-elixir: repo: ant-sdk @@ -245,6 +281,8 @@ components: - rust/library-reference.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-cli: repo: ant-client @@ -263,6 +301,8 @@ components: - guides/prepare-a-wallet-for-uploads.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md # === ant-node === @@ -283,6 +323,8 @@ components: - architecture/system-overview.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-devnet: repo: ant-node @@ -294,6 +336,8 @@ components: - sdk/start-the-local-daemon.md - guides/set-up-a-local-network.md - guides/test-your-application.md + feeds_skills: + - skills/autonomi-developer/SKILL.md # === Foundational single-crate repos === @@ -351,6 +395,8 @@ components: - core-concepts/payment-model.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md self_encryption: repo: self_encryption @@ -366,6 +412,8 @@ components: - core-concepts/keys-addresses-and-datamaps.md - reference/source-repositories.md - reference/glossary.md + feeds_skills: + - skills/autonomi-developer/SKILL.md evmlib: repo: evmlib @@ -379,6 +427,8 @@ components: - guides/estimate-costs-and-handle-upload-payments.md - sdk/how-to-guides/use-external-signers-for-upload-payments.md - reference/source-repositories.md + feeds_skills: + - skills/autonomi-developer/SKILL.md ant-merkle: repo: ant-merkle diff --git a/skills/autonomi-developer/CHANGELOG.md b/skills/autonomi-developer/CHANGELOG.md new file mode 100644 index 0000000..ee999ac --- /dev/null +++ b/skills/autonomi-developer/CHANGELOG.md @@ -0,0 +1,42 @@ +# Changelog - autonomi-developer skill + +All notable changes to this skill are recorded here. + +## [Unreleased] + +## [0.1.1-draft] - 2026-04-30 + +### Changed +- Reverified the skill against the current docs layout and current upstream source heads. +- Added `ant-protocol` to the skill's verification scope for protocol-adjacent operational guidance. +- Refreshed SDK guidance to point at the current file-cost endpoint and current shared prepare/finalize semantics. +- Updated the maintenance guide to match the current component mapping and re-verification triggers. +- Refreshed the pinned `ant-client` and `ant-protocol` verification commits and clarified `LocalDevnet::create_funded_client(...)` in the Direct Rust playbook. + +### Verified Against +- ant-sdk: 1cbfb3e92cb4309f29e92b5609837812027f0a67 +- ant-client: 8b2c9c606a1223f105fed9aa2b56310b6a6763da +- ant-node: 23aee15cae33a17257ba833b2b98ed8a7a12e684 +- ant-protocol: 65651f3a3243af8299a3e8d63385cba846ef88a4 +- self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 +- evmlib: 225acbb1af613193bcc8264b6ede4d7e4a7ac607 + +## [0.1.0-draft] - 2026-04-22 + +### Added +- Initial in-repo `autonomi-developer` skill package. +- Operational path selector for SDK, CLI, Direct Rust, and MCP work. +- Exact golden flows for daemon health, SDK public data round-trip, CLI public file round-trip, and local devnet startup checks. +- Live reference table for the current docs site. +- Skill version manifest and maintenance guide. + +### Changed +- Rebuilt the skill around the current docs and current upstream source artifacts instead of the earlier standalone draft. +- Reduced deep network internals so the skill stays focused on building and shipping applications. + +### Verified Against +- ant-sdk: 2ed9b14bda42fbdc604a173cc1af27be0964908f +- ant-client: b0c501a163c1a95bdbfc703892b88a8a91f7e482 +- ant-node: 5a5d7d4fed766cd56d0f97f337fcd5ff049bea6a +- self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 +- evmlib: 82f2fccff243b48de0e04ceb71ccb2aa17d810af diff --git a/skills/autonomi-developer/MAINTAINING.md b/skills/autonomi-developer/MAINTAINING.md new file mode 100644 index 0000000..9322592 --- /dev/null +++ b/skills/autonomi-developer/MAINTAINING.md @@ -0,0 +1,154 @@ +# Maintaining the `autonomi-developer` skill + +This skill lives in `skills/autonomi-developer/` and follows the same source-of-truth model as the rest of the docs repo. + +## Files that move together + +Every release or re-verification pass updates these files together: + +- `SKILL.md` +- `version.json` +- `CHANGELOG.md` + +## Current scope + +This skill is intentionally practical. It covers: + +- SDK and daemon workflows +- CLI workflows +- Direct Rust with `ant-core` +- MCP setup rules +- read-only versus upload-enabled architecture +- local devnet testing +- wallet and payment basics needed to build safely + +It does not try to teach the deeper routing, transport, or cryptography internals in detail. It only keeps the minimum protocol-adjacent guidance needed to stay safe around devnet manifests and prepare/finalize upload flows. + +## Verification inputs + +Use the same workflow the docs use: + +1. Source audit +2. Draft +3. Verify + +Read these repo files before changing the skill: + +- `CLAUDE.md` +- `planning/verification-workflow.md` +- `repo-registry.yml` +- `component-registry.yml` + +## Components that currently feed this skill + +The skill is mapped through `feeds_skills:` in `component-registry.yml`. + +Current component coverage: + +- `antd`, `openapi`, `proto`, `ant-dev`, and `antd-mcp` +- the documented `antd-*` language bindings with standalone current-doc pages +- `ant-core` +- `ant-cli` +- `ant-node` +- `ant-devnet` +- `self_encryption` +- `evmlib` +- `ant-protocol` + +Treat these repos as the skill's re-verification inputs today: + +- `ant-sdk` +- `ant-client` +- `ant-node` +- `self_encryption` +- `evmlib` +- `ant-protocol` + +## When to re-verify + +Run a skill verification pass when: + +- one of the mapped repos changes in a way that can affect the skill +- a docs page URL baked into `SKILL.md` changes +- a golden flow in the skill stops matching the current docs or source artifacts +- the skill adds or removes path coverage +- protocol-adjacent guidance in the skill changes, such as devnet-manifest behavior or prepare/finalize upload semantics + +## What to verify + +### SDK path + +Check current daemon defaults and exact route names against the active `ant-sdk` source artifacts. + +Use these artifacts first: + +- `antd/openapi.yaml` +- `antd/proto/` +- `docs/sdk/reference/rest-api.md` +- `docs/sdk/reference/daemon-command-reference.md` + +### CLI path + +Check command names, global-flag placement, and quickstart flows against the active `ant-client` sources. + +Use these artifacts first: + +- `docs/cli/use-the-cli.md` +- `docs/cli/command-reference.md` +- current help output if you have the repo checked out locally + +### Direct Rust path + +Check named `ant-core` surfaces against the active `ant-client` sources. + +Use these artifacts first: + +- `docs/rust/build-directly-in-rust.md` +- `docs/rust/library-reference.md` +- upstream `ant-client` examples when signatures or helper names matter + +### MCP path + +Check MCP setup rules, tool names, and daemon discovery against the active `ant-sdk` sources. + +Use these artifacts first: + +- `docs/mcp/use-the-autonomi-mcp-server.md` +- `docs/mcp/mcp-server-reference.md` +- `antd-mcp/README.md` when the docs are being refreshed at the same time + +### Concepts and safety rules + +Check these against the relevant docs pages and source repos: + +- public versus private data +- wallet key versus public address versus `DataMap` +- self-encryption behavior +- payment and wallet handling +- local devnet workflow +- protocol-adjacent operational details such as devnet-manifest handoff and prepare/finalize variants + +## Update order + +1. Update `SKILL.md`. +2. Update `version.json` with the same version, date, and verified commits. +3. Add a matching entry to `CHANGELOG.md`. + +## Versioning + +Use Semantic Versioning with these rules: + +- major: breaking changes to skill loading or manifest shape +- minor: new paths, new verified examples, or new operational capabilities +- patch: wording fixes, pointer fixes, or re-verification-only updates + +Keep the `-draft` suffix until the skill has gone through at least one deliberate re-verification pass after landing in the repo. + +## Pre-merge checklist + +- [ ] `SKILL.md`, `version.json`, and `CHANGELOG.md` agree on the version. +- [ ] `verified_date` and `published_date` match. +- [ ] every `verified_commits` entry is a real SHA. +- [ ] every live-docs URL in `SKILL.md` resolves. +- [ ] no hard-coded detail was added without a matching verification source. +- [ ] the skill still avoids guessed SDK methods, CLI flags, MCP tool names, and protocol payload shapes. diff --git a/skills/autonomi-developer/SKILL.md b/skills/autonomi-developer/SKILL.md new file mode 100644 index 0000000..33b7ac1 --- /dev/null +++ b/skills/autonomi-developer/SKILL.md @@ -0,0 +1,426 @@ +--- +name: autonomi-developer +description: | + Build applications, automations, and AI workflows on the Autonomi Network. + Use this skill when the user wants to store or retrieve data, add Autonomi + storage to an application, build read-only or upload-enabled features, use + the `antd` daemon and SDK bindings, work from the `ant` CLI, build directly + in Rust with `ant-core`, or expose Autonomi through an MCP-compatible client. + Do not use for Autonomi 1.0, the MaidSafe-era network, `ant-quic`, or + general EVM work that is not part of building on Autonomi. +version: 0.1.1-draft +license: MIT +repository: https://github.com/WithAutonomi/autonomi-developer-docs +homepage: https://docs.autonomi.com/developers +author: Autonomi Developer Documentation +keywords: + - autonomi + - ant-sdk + - antd + - ant-client + - ant-core + - ant + - ant-protocol + - mcp + - devnet + - datamap + - self-encryption + - uploads + - read-only + +# Verification block. Re-verify before changing stable claims or examples. +verified_date: 2026-04-30 +verification_mode: current-merged-truth +verified_commits: + ant-sdk: 1cbfb3e92cb4309f29e92b5609837812027f0a67 + ant-client: 8b2c9c606a1223f105fed9aa2b56310b6a6763da + ant-node: 23aee15cae33a17257ba833b2b98ed8a7a12e684 + ant-protocol: 65651f3a3243af8299a3e8d63385cba846ef88a4 + self_encryption: 5f9d1646231da7ca2ce60e84d010acfb6d9c29d0 + evmlib: 225acbb1af613193bcc8264b6ede4d7e4a7ac607 + +version_manifest_url: https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/version.json +canonical_docs_url: https://docs.autonomi.com/developers +--- + +# Autonomi Developer + +This skill makes you effective at building on the Autonomi Network without making the user read the full docs set first. Treat it as an operational guide: pick the correct Autonomi path, fetch one live reference when exact interface details matter, and do not invent Autonomi-specific APIs. + +## Scope + +Use this skill when the task is about: + +- storing or retrieving data on Autonomi +- adding Autonomi storage to an application +- building read-only or upload-enabled features +- using `antd` and the SDK bindings +- using the `ant` CLI +- building directly in Rust with `ant-core` +- exposing Autonomi through an MCP-compatible client +- testing with a local devnet before public-network deployment + +Do not use this skill for: + +- Autonomi 1.0 or anything under the MaidSafe org unless the user explicitly wants historical context +- `ant-quic` or older transport docs +- general EVM, Arbitrum, IPFS, or Filecoin work unrelated to building on Autonomi + +## Operating Rules + +1. Check whether a newer verified version of this skill exists: + +```bash +curl -fsSL https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/version.json +``` + +If the published `version` is newer, tell the user this copy may be stale and offer to reload it. If the fetch fails, continue silently. For an unpublished draft, that usually means the skill is not on `main` yet. + +2. Pick one path before you start coding: SDK, CLI, Direct Rust, or MCP. + +3. Fetch one live reference page once per task when you need volatile details such as install steps, exact REST or gRPC schemas, binding-specific helpers, CLI flags, MCP tool names, devnet-manifest fields, or prepare/finalize payload shapes. + +4. Do not invent Autonomi-specific details. If this skill does not name a route, flag, method, env var, or tool and you have not fetched the live reference, do not guess it. + +5. For anything that uploads data, start on a local devnet first unless the user explicitly wants public-network work. + +6. Ask before installing software, configuring wallets, or touching real ANT on a public network. + +## Path Selector + +| Path | Choose it when the user wants to... | Fetch first when details matter | +|------|-------------------------------------|---------------------------------| +| SDK | Build an application in Python, JavaScript, TypeScript, Rust, Go, Java, C#, Kotlin, Swift, Ruby, PHP, C++, Dart, or Zig through a local daemon | language page plus REST or gRPC reference | +| CLI | Work from the shell, script uploads or downloads, inspect wallets, or do operational workflows | CLI command reference | +| Direct Rust | Build daemon-free Rust with direct network control or local devnet helpers | Rust getting-started page plus library reference | +| MCP | Let an MCP-compatible client talk to Autonomi through `antd` | MCP setup page plus MCP server reference | + +If the user has not chosen a path, recommend SDK first. It is the best fit for most application work. + +## Fast Lookup Discipline + +Use this workflow to stay fast without guessing: + +1. Decide whether the feature is read-only or upload-enabled. +2. Pick a path. +3. Check the local prerequisite for that path. +4. Fetch one live page for the path-specific details. +5. Reuse that page for the rest of the task instead of re-fetching several pages. + +For SDK and MCP work, the fastest first check is usually: + +```bash +curl http://localhost:8082/health +``` + +Expected shape: + +```json +{ + "status": "ok", + "network": "default" +} +``` + +Treat `network` as environment-dependent. On a local devnet, it is typically `local` instead of `default`. + +If the user is on a non-default host or port, ask for the base URL instead of assuming `localhost:8082`. + +## Path Playbooks + +### SDK + +Choose SDK when the user wants normal application development in a supported language. This path goes through `antd`. + +Current daemon defaults: + +- REST: `http://localhost:8082` +- gRPC: `localhost:50051` +- non-default ports can be discovered through the `daemon.port` file written by `antd` + +Current shared daemon surfaces you can rely on at this commit: + +- `GET /health` +- `POST /v1/data/public` +- `GET /v1/data/public/{addr}` +- `POST /v1/data/private` +- `GET /v1/data/private` +- `POST /v1/data/cost` +- `POST /v1/files/cost` +- `GET /v1/wallet/address` +- `GET /v1/wallet/balance` +- `POST /v1/wallet/approve` +- `POST /v1/data/prepare` +- `POST /v1/upload/prepare` +- `POST /v1/upload/finalize` + +Golden public-data round trip: + +```bash +DATA_B64=$(printf 'Hello, Autonomi!' | base64) + +curl -X POST http://localhost:8082/v1/data/public \ + -H "Content-Type: application/json" \ + -d "{\"data\":\"$DATA_B64\"}" + +curl http://localhost:8082/v1/data/public/
+``` + +Keep these rules straight: + +- REST binary payloads are base64 inside JSON. +- `POST /v1/data/public` returns a public address. +- `POST /v1/data/private` returns a serialized `DataMap`. +- `GET /v1/data/private` needs the `data_map` query parameter. +- read-only daemon work does not require `AUTONOMI_WALLET_KEY` + +Current documented binding entry points: + +- Python: `AntdClient()` or `AsyncAntdClient()` +- JavaScript and TypeScript: `createClient()` +- Go: `NewClient(...)` +- Rust SDK: `Client::new(...)` + +Standalone binding pages also exist for Java, C#, Kotlin, Swift, Ruby, PHP, C++, Dart, and Zig. Fetch the language-specific page when the user is working in one of those SDKs. + +The bindings overview is not exhaustive for every standalone binding page. Use the direct language page when one exists instead of assuming the overview lists everything. + +Before writing SDK code beyond health checks and the public-data round trip, fetch the binding page for the user's language. + +### CLI + +Choose CLI when the user wants direct shell workflows, scripts, CI automation, wallet inspection, or quick operational tasks without `antd` in the data path. + +Current CLI rules that matter in practice: + +- data commands do not require the daemon +- root flags such as `--bootstrap`, `--devnet-manifest`, `--allow-loopback`, and `--evm-network` come before the subcommand +- the direct-network `ant` CLI's main top-level groups are `file`, `chunk`, `wallet`, `node`, and `update` +- uploads and wallet commands require `SECRET_KEY` + +Golden public-file flow on a local devnet: + +```bash +SECRET_KEY=0x... ant \ + --devnet-manifest /tmp/devnet.json \ + --allow-loopback \ + --evm-network local \ + file upload photo.jpg --public + +ant \ + --devnet-manifest /tmp/devnet.json \ + --allow-loopback \ + --evm-network local \ + file download
-o photo_copy.jpg +``` + +Keep these rules straight: + +- private file uploads save a local `.datamap` file instead of returning a public address +- private file downloads use `--datamap ` +- public downloads do not need a wallet + +For anything beyond these patterns, fetch the CLI command reference first. + +### Direct Rust + +Choose Direct Rust when the user wants daemon-free Rust, native Rust types, direct client control, or built-in local devnet helpers. + +Current `ant-core` surfaces you can name safely: + +- `Client::connect(...)` +- `with_wallet(...)` +- `data_upload(...)` +- `data_download(...)` +- `file_upload_with_mode(...)` +- `file_download(...)` +- `data_map_store(...)` +- `data_map_fetch(...)` +- `LocalDevnet::start_minimal()` +- `LocalDevnet::create_funded_client(...)` + +Use Direct Rust when the user needs those native surfaces. Do not infer full method signatures or argument shapes from memory; fetch the Rust getting-started page and the library reference before writing the code. + +### MCP + +Choose MCP when an MCP-compatible client should use Autonomi through structured tools instead of raw HTTP. + +Current MCP setup facts: + +- server command: `antd-mcp` +- install pattern: + +```bash +pip install "antd[rest]" +pip install -e antd-mcp/ +``` + +- stdio mode: `antd-mcp` +- SSE mode: `antd-mcp --sse` +- daemon discovery order: + - `ANTD_BASE_URL` + - `daemon.port` + - `http://127.0.0.1:8082` + +Do not memorize MCP tool names or schemas in this skill. Fetch the MCP server reference when the task is MCP-specific. + +## Concepts That Affect Implementation + +### Public vs private data + +Autonomi has one underlying storage primitive: encrypted chunks. Public and private data differ mainly in where the `DataMap` lives. + +- public data returns an address that can be shared and fetched later +- private data returns a `DataMap` that the caller must keep +- if private retrieval is failing, check for a missing or wrong `DataMap` before anything else + +### Wallet keys vs retrieval material + +These are different things: + +- `AUTONOMI_WALLET_KEY` pays for uploads through `antd` +- `SECRET_KEY` pays for uploads and wallet commands through `ant` +- an attached `Wallet` pays for uploads through `ant-core` +- a public address retrieves public data +- a `DataMap` retrieves private data + +Do not collapse those concepts into one key-handling model. + +### Read-only vs upload-enabled features + +This is the first architectural split to make. + +If the feature is read-only: + +- no ANT is required +- no gas is required +- no wallet is required +- the daemon can run without `AUTONOMI_WALLET_KEY` + +If the feature uploads data: + +- local devnet gives you funded local test wallets +- public networks need ANT plus gas on the selected EVM network +- wallet setup becomes part of the feature, not an afterthought + +### Local devnet first + +For upload-enabled work, the shortest safe loop is: + +```bash +ant dev start --ant-node-dir ../ant-node +ant dev status +ant dev wallet show +curl http://localhost:8082/health +``` + +The local environment gives you a running devnet, `antd --network local`, and a funded local wallet. Stop it with: + +```bash +ant dev stop +``` + +These `ant dev` commands come from the `ant-dev` package in `ant-sdk`, not from the direct-network `ant` CLI in `ant-client`. + +The devnet-manifest handoff is shared across client and node code. Treat its exact field shape as volatile and fetch the live reference before automating around it. + +### Payment modes and external signing + +Current upload payment modes are: + +- `auto` +- `merkle` +- `single` + +Use `auto` unless the user has a reason to force the behavior. If the user wants explicit cost estimation before an upload, use the current cost endpoints or the path-specific reference page. + +The prepare/finalize flows are also shared across multiple layers now. Treat exact prepare payload fields, finalize variants, and Merkle versus wave-batch response shapes as volatile and fetch the live reference before writing code around them. + +## Common Failures + +### Daemon health check fails + +The daemon is not running, it is on a different port, or the task should be using CLI or Direct Rust instead of SDK or MCP. + +### `503` on daemon write routes + +`antd` is reachable but wallet configuration is missing. Check `AUTONOMI_WALLET_KEY` or switch to an external-signer flow. + +### `insufficient funds` + +Distinguish between missing ANT and missing gas. Do not tell the user to fund the wallet without identifying which balance is missing. + +### Private retrieval fails + +Check the `DataMap` first. Private content still needs the retrieval metadata even after the content has already been paid for. + +### CLI command shape looks wrong + +Check whether the root flags were placed after the subcommand. In `ant`, global flags belong before `file`, `chunk`, `wallet`, `node`, or `update`. + +### Tests fail against the daemon surface + +Check whether the test expects raw bytes over REST. Current REST binary payloads are JSON with base64 in the `data` field. + +## Hard Constraints + +- Do not reference Autonomi 1.0 as if it were current. +- Do not reference `ant-quic` in current Autonomi work. +- Do not guess endpoints, flags, method names, or contract details. +- Do not put real wallet keys into committed code. +- Do not walk a user into public-network uploads without checking that they understand the money and irreversibility involved. +- Stay on one Autonomi path unless the user explicitly asks for a comparison. + +## Live References + +Use these pages as the first lookup for current details: + +| Need | Live page | +|------|-----------| +| Overview | `https://docs.autonomi.com/developers` | +| SDK entry point | `https://docs.autonomi.com/developers/sdk/install` | +| SDK first upload | `https://docs.autonomi.com/developers/sdk/install/store-data-on-the-network` | +| SDK first retrieval | `https://docs.autonomi.com/developers/sdk/install/retrieve-data-from-the-network` | +| SDK store and retrieve guide | `https://docs.autonomi.com/developers/sdk/install/how-to-guides/store-and-retrieve-data` | +| SDK daemon as service | `https://docs.autonomi.com/developers/sdk/install/how-to-guides/use-the-daemon-as-a-local-service` | +| REST API | `https://docs.autonomi.com/developers/sdk/install/reference/rest-api` | +| gRPC services | `https://docs.autonomi.com/developers/sdk/install/reference/grpc-services` | +| Daemon command reference | `https://docs.autonomi.com/developers/sdk/install/reference/daemon-command-reference` | +| Language bindings overview | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/overview` | +| Python SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/python` | +| JavaScript SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/javascript` | +| TypeScript SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/typescript` | +| Rust SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/rust` | +| Go SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/go` | +| Java SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/java` | +| C# SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/csharp` | +| Kotlin SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/kotlin` | +| Swift SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/swift` | +| Ruby SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/ruby` | +| PHP SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/php` | +| C++ SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/cpp` | +| Dart SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/dart` | +| Zig SDK | `https://docs.autonomi.com/developers/sdk/install/reference/language-bindings/zig` | +| CLI quickstart | `https://docs.autonomi.com/developers/cli/use-the-cli` | +| CLI command reference | `https://docs.autonomi.com/developers/cli/command-reference` | +| Direct Rust quickstart | `https://docs.autonomi.com/developers/developing-in-rust/build-directly-in-rust` | +| Rust library reference | `https://docs.autonomi.com/developers/developing-in-rust/library-reference` | +| MCP setup | `https://docs.autonomi.com/developers/mcp/use-the-autonomi-mcp-server` | +| MCP reference | `https://docs.autonomi.com/developers/mcp/mcp-server-reference` | +| Local devnet | `https://docs.autonomi.com/developers/guides/set-up-a-local-network` | +| Prepare a wallet | `https://docs.autonomi.com/developers/guides/prepare-a-wallet-for-uploads` | +| Payments and cost estimation | `https://docs.autonomi.com/developers/guides/estimate-costs-and-handle-upload-payments` | +| Read-only features | `https://docs.autonomi.com/developers/guides/build-read-only-features` | +| Testing | `https://docs.autonomi.com/developers/guides/test-your-application` | +| Deploy to mainnet | `https://docs.autonomi.com/developers/guides/deploy-to-mainnet` | +| Data types | `https://docs.autonomi.com/developers/core-concepts/data-types` | +| Keys, addresses, and DataMaps | `https://docs.autonomi.com/developers/core-concepts/keys-addresses-and-datamaps` | +| Self-encryption | `https://docs.autonomi.com/developers/core-concepts/self-encryption` | +| Payment model | `https://docs.autonomi.com/developers/core-concepts/payment-model` | +| System overview | `https://docs.autonomi.com/developers/architecture/system-overview` | +| Glossary | `https://docs.autonomi.com/developers/reference-extras/glossary` | +| Source repositories | `https://docs.autonomi.com/developers/reference-extras/source-repositories` | + +## If Something Conflicts + +Trust the live docs over stale memory. If the live docs and this skill disagree, tell the user the skill may be stale, use the live docs for the task in front of you, and update the skill package in this repo afterward. diff --git a/skills/autonomi-developer/version.json b/skills/autonomi-developer/version.json new file mode 100644 index 0000000..ea61aa9 --- /dev/null +++ b/skills/autonomi-developer/version.json @@ -0,0 +1,25 @@ +{ + "skill": "autonomi-developer", + "version": "0.1.1-draft", + "published_date": "2026-04-30", + "status": "draft", + "canonical_skill_url": "https://raw.githubusercontent.com/WithAutonomi/autonomi-developer-docs/main/skills/autonomi-developer/SKILL.md", + "canonical_docs_url": "https://docs.autonomi.com/developers", + "repository": "https://github.com/WithAutonomi/autonomi-developer-docs", + "verification_mode": "current-merged-truth", + "verified_commits": { + "ant-sdk": "1cbfb3e92cb4309f29e92b5609837812027f0a67", + "ant-client": "8b2c9c606a1223f105fed9aa2b56310b6a6763da", + "ant-node": "23aee15cae33a17257ba833b2b98ed8a7a12e684", + "ant-protocol": "65651f3a3243af8299a3e8d63385cba846ef88a4", + "self_encryption": "5f9d1646231da7ca2ce60e84d010acfb6d9c29d0", + "evmlib": "225acbb1af613193bcc8264b6ede4d7e4a7ac607" + }, + "covers_paths": [ + "sdk", + "cli", + "direct-rust", + "mcp" + ], + "notes": "Reverified current-main draft with protocol-adjacent operational scope. The canonical raw URLs resolve after this draft lands on main. Re-verify before promoting to a non-draft version." +}