docs: add Agent-friendly entry index and source-derived API specs

[abn2357]

Summary

• Add docs/llms.txt as an Agent entry index linking the API references and node-operation pages (served at /llms.txt).
• Add source-derived API specs: OpenAPI (docs/api/openapi.yaml), OpenRPC (docs/api/openrpc.json), and per-endpoint HTTP / JSON-RPC spec files under docs/api/specs/.

Spec generation

The specs are produced with a base + per-endpoint overlay workflow: each HTTP path and JSON-RPC method is derived from a source-extracted base and refined by an endpoint-specific overlay, replacing the earlier monolithic generation approach. This yields more accurate per-interface fragments, which bundle into the top-level openapi.yaml / openrpc.json.

Spec quality assurance

The regenerated definitions go through a fine-grained, layered audit and cross-validation across multiple large language models — covering error response modeling, JSON content typing, integer formats, nested object schemas, and JSON-RPC result shapes — for higher-quality SDK generation.

Unrelated fixes bundled in

The following two items are not part of the Agent-friendly docs theme. They address two optimization items surfaced by the routine AI audit report and are included here for convenience:

• Declare documentation-en as the authoritative source on the home page, with this Chinese repository as the translation that follows it.
• Add an SR-setup safety note: chmod 600 the config, never commit a config file with a real private key, and prefer keystore.

Test plan

• mkdocs build succeeds with the new pages and mkdocs.yml nav entry.
• /llms.txt resolves and its links point to valid pages.
• Generated OpenAPI / OpenRPC specs parse without errors.

[vivian1912]

The direction is valuable — generating machine-readable specs from java-tron source ground truth is the right idea. But I'd recommend reworking the PR before merging, primarily around where these artifacts live and how strict the schemas should be.

1. Generated artifacts should live alongside the source they describe, not in the docs repo
   The ~21k-line / 130+-file payload here is almost entirely auto-generated. The current arrangement may create a coupling problem.
   Where things should ideally live:

• java-tron (or a dedicated tron-api-specs): api/openapi.yaml, api/openrpc.json, api/specs/*, scripts/generate_api_specs.py — versioned alongside the code they describe; regenerated and validated in CI
• documentation-zh (here): interface-definitions.md + llms.txt only — short pointer pages linking to the specs in their canonical home
  Reference: ethereum/execution-apis does exactly this — JSON-RPC specs in their own repo, narrative docs link to them.

2. Schema strictness is too loose for practical SDK generation

• Required fields aren't declared. createaccount.yaml lists owner_address and account_address in properties but doesn't include them in a required: [...] array — so generated clients will treat every field as optional. Reading the actuator validation in CreateAccountActuator.java#L91-94, owner_address is clearly required (validated as a non-null TRON address). The script could derive required lists from the actuator validation rules.
• Enum types are flattened to object. In freezebalancev2.yaml, resource is typed as object with additionalProperties: true, but the underlying field is a ResourceCode enum (BANDWIDTH | ENERGY | TRON_POWER). Other proto enum fields in the schema get the same treatment. Generated SDKs lose type safety on these.
• additionalProperties: true is the default on nearly every object schema. This effectively says "any unknown field is acceptable" — useful for forward-compat, but combined with (a) and (b) it means consumers end up with Map<String, Any> for most request and response payloads.
• Error response shape isn't modeled. Only HTTP 200 and 404 are described. The actual TRON HTTP error path is HTTP 200 with {"Error": " : "} in the body — see Util.java (jsonObject.put("Error", e.getClass() + " : " + e.getMessage())). Without this modeled as an alternative schema (e.g., via oneOf), generated SDKs deserialize both 200 responses into the "success" type with all fields nullable. Clients have to fall back to manual string-checks for the Error key, defeating the type-safety motivation for using OpenAPI.

[abn2357]

The direction is valuable — generating machine-readable specs from java-tron source ground truth is the right idea. But I'd recommend reworking the PR before merging, primarily around where these artifacts live and how strict the schemas should be.

1. Generated artifacts should live alongside the source they describe, not in the docs repo
   The ~21k-line / 130+-file payload here is almost entirely auto-generated. The current arrangement may create a coupling problem.
   Where things should ideally live:

• java-tron (or a dedicated tron-api-specs): api/openapi.yaml, api/openrpc.json, api/specs/*, scripts/generate_api_specs.py — versioned alongside the code they describe; regenerated and validated in CI
• documentation-zh (here): interface-definitions.md + llms.txt only — short pointer pages linking to the specs in their canonical home
  Reference: ethereum/execution-apis does exactly this — JSON-RPC specs in their own repo, narrative docs link to them.

2. Schema strictness is too loose for practical SDK generation

• Required fields aren't declared. createaccount.yaml lists owner_address and account_address in properties but doesn't include them in a required: [...] array — so generated clients will treat every field as optional. Reading the actuator validation in CreateAccountActuator.java#L91-94, owner_address is clearly required (validated as a non-null TRON address). The script could derive required lists from the actuator validation rules.
• Enum types are flattened to object. In freezebalancev2.yaml, resource is typed as object with additionalProperties: true, but the underlying field is a ResourceCode enum (BANDWIDTH | ENERGY | TRON_POWER). Other proto enum fields in the schema get the same treatment. Generated SDKs lose type safety on these.
• additionalProperties: true is the default on nearly every object schema. This effectively says "any unknown field is acceptable" — useful for forward-compat, but combined with (a) and (b) it means consumers end up with Map<String, Any> for most request and response payloads.
• Error response shape isn't modeled. Only HTTP 200 and 404 are described. The actual TRON HTTP error path is HTTP 200 with {"Error": " : "} in the body — see Util.java (jsonObject.put("Error", e.getClass() + " : " + e.getMessage())). Without this modeled as an alternative schema (e.g., via oneOf), generated SDKs deserialize both 200 responses into the "success" type with all fields nullable. Clients have to fall back to manual string-checks for the Error key, defeating the type-safety motivation for using OpenAPI.

Thank you for your suggestions.

1. The previous generic generator did indeed produce overly loose schemas. The new spec files now use a base + overlay approach — a base spec for common content, with an overlay for each individual endpoint. Additionally, I have performed fine-grained, per-spec-file hierarchical auditing and multi-model cross-validation. Please kindly review it again. Thank you.

2. All generation-related scripts have been removed, and only the final artifacts are retained. For now, we prefer to keep a copy in the documentation repo first, since the spec files have a one-to-one correspondence with the API markdown files. Later, I will reach out to the java-tron community to see if they are willing to host them. We'll make the final decision — whether to maintain copies in both repos or only in one.

[vivian1912]

Broken directory links in interface-definitions.md

The second table in docs/api/interface-definitions.md links to directories:

| HTTP API | [`specs/http/`](specs/http/) |
| JSON-RPC API | [`specs/json-rpc/`](specs/json-rpc/) |

MkDocs does not generate directory index pages by default, and there is no index.md under specs/http/ or specs/json-rpc/. Once built, both links will 404 on the published site.

[vivian1912]

additionalProperties: true on 71%（110/154）top-level schemas

Verified against the merged openapi.yaml in this PR:

• 154 top-level schemas in total
• 110 (71%) have additionalProperties: true
• 44 have additionalProperties: false
• Counting all nesting levels: 124 true vs 68 false

openrpc.json is clean (0 true / 21 false). The problem is isolated to the HTTP OpenAPI spec.

Where it lands: the PR fixed additionalProperties: false on the request-body wrapper schemas
(e.g. FreezeBalanceV2ContractRequest → 43 Request-suffix schemas are all false, zero true),
but the proto-derived schemas without the Request suffix (e.g. FreezeBalanceV2Contract) — which are
what response/nested object payloads resolve to — were left at true. Only 1 of 111 non-Request schemas
has additionalProperties: false.

Concretely, 105 of the 110 true schemas are reachable only from responses or as nested types,
including high-traffic ones: Account, Block, Transaction, BlockHeader, AccountResourceMessage,
ChainParameters, DelegatedResource, etc.

SDK impact: request construction is type-safe, but every response deserializes through
Map<String, Any> for unknown fields, and nested enum/object fields lose their declared types
in generated client code. This means SDK generation — one of the stated motivations for these specs —
is not actually achieved.

[abn2357]

additionalProperties: true on 71%（110/154）top-level schemas

Verified against the merged openapi.yaml in this PR:

• 154 top-level schemas in total
• 110 (71%) have additionalProperties: true
• 44 have additionalProperties: false
• Counting all nesting levels: 124 true vs 68 false

openrpc.json is clean (0 true / 21 false). The problem is isolated to the HTTP OpenAPI spec.

Where it lands: the PR fixed additionalProperties: false on the request-body wrapper schemas (e.g. FreezeBalanceV2ContractRequest → 43 Request-suffix schemas are all false, zero true), but the proto-derived schemas without the Request suffix (e.g. FreezeBalanceV2Contract) — which are what response/nested object payloads resolve to — were left at true. Only 1 of 111 non-Request schemas has additionalProperties: false.

Concretely, 105 of the 110 true schemas are reachable only from responses or as nested types, including high-traffic ones: Account, Block, Transaction, BlockHeader, AccountResourceMessage, ChainParameters, DelegatedResource, etc.

SDK impact: request construction is type-safe, but every response deserializes through Map<String, Any> for unknown fields, and nested enum/object fields lose their declared types in generated client code. This means SDK generation — one of the stated motivations for these specs — is not actually achieved.

Thank you. This has been fixed, along with the 404 issue for the link above. (Note: Adding an index.md file is not suitable here, so that approach was not adopted. Local deployment tests still return a 404 Github page; the link will only redirect to the correct GitHub page after this PR is merged.) The changes were amended into the latest commit rather than submitted separately.