docs(ai): align energy purchase, security, and agent contracts

.github/workflows/gh-pages.yml

@@ -3,19 +3,38 @@ on:
   push:
     branches:
       - main  # Trigger this workflow whenever the main branch changes
-    workflow_dispatch:    # Allow manual triggering of this workflow via the "Run workflow" button on the GitHub UI Actions tab
+  pull_request:
+    branches:
+      - main  # Validate AI contracts and strict docs builds before merge
+  workflow_dispatch:    # Allow manual triggering of this workflow via the "Run workflow" button on the GitHub UI Actions tab
+  schedule:
+    - cron: '17 2 * * 1'  # Weekly live contract check, Monday 02:17 UTC
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v4  # Action that checks out the repository
+      uses: actions/checkout@v7  # Action that checks out the repository
       with:
         persist-credentials: false   # Disable auto-injection of GITHUB_TOKEN so a higher-privilege token can be supplied in later steps
         fetch-depth: 0   # Required by mkdocs-git-revision-date-localized-plugin to compute per-page last-updated
 
+    - name: Setup Node.js
+      uses: actions/setup-node@v7
+      with:
+        node-version: 20
+
+    - name: Verify AI-readable source consistency
+      run: node scripts/verify-ai-consistency.mjs
+
+    - name: Run live API agent acceptance
+      if: github.event_name != 'pull_request'
+      run: |
+        node scripts/api-acceptance.mjs --json > docs/developers/apis/agent-acceptance-latest.json
+        node -e "const r=require('./docs/developers/apis/agent-acceptance-latest.json'); if(!r.success||r.passed!==r.total) process.exit(1)"
+
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v7
       with:
         python-version: 3.x   # Install Python
 
@@ -31,18 +50,23 @@ jobs:
         pip install mkdocs-git-revision-date-localized-plugin==1.4.7   # per-page last-updated from git history
 
     - name: Build the document
-      run: mkdocs build  # Build the MkDocs site
+      run: mkdocs build --strict
 
     - name: Verify security metadata output
       run: |
         test -f site/.nojekyll
         test -f site/.well-known/security.txt
         cmp docs/.well-known/security.txt site/.well-known/security.txt
+        test -f site/ai_support/cli_and_sdk.md
+        cmp docs/ai_support/cli_and_sdk.md site/ai_support/cli_and_sdk.md
+        grep -q 'type="text/markdown"' site/ai_support/cli_and_sdk/index.html
+        test -f site/developers/apis/agent-acceptance-latest.json
 
     - name: Add CNAME file
       run: echo 'docs.justlend.org' > site/CNAME
 
     - name: Deploy
+      if: github.event_name != 'pull_request'
       uses: JamesIves/github-pages-deploy-action@v4
       with:
         token: ${{ secrets.TOKEN}}

CHANGELOG.md

@@ -10,6 +10,21 @@ For the JustLend protocol itself, see governance proposals on [forum.justlend.or
 
 ## [Unreleased]
 
+### Added — 2026-08-19 AI-readability contract pass
+
+- Added first-class CLI and V2 Utils discovery across navigation, `llms.txt`, `llms-full.txt`, AI source routing, JSON-LD, and a dedicated install/safety guide.
+- Synced the agent surfaces to CLI `1.0.1`, full MCP `1.1.3`, and Skills `1.1.1`, including versioned success/error envelopes and published output schemas.
+- Regenerated the site-local 104-tool MCP catalog with `outputSchema` coverage on every tool and documented the bundled Skills server's 9 structured outputs.
+- Published canonical raw Markdown beside every rendered page and advertised it with `rel="alternate" type="text/markdown"` plus a visible source link.
+- Added deterministic AI-consistency checks and a weekly, structured 9-probe live API acceptance artifact in CI.
+
+### Fixed — 2026-08-19 AI-readability contract pass
+
+- Reconciled the market inventory to **24 total (18 active + 6 legacy)** after expanding `app.justlend.org/marketNew` and cross-checking `/lend/jtoken` plus the MCP chain catalog; added the previously omitted active `jU` market everywhere.
+- Corrected `/lend/account`: `addresses` is optional, omission returns the global account index, and the endpoint-specific default `pageSize` is 50.
+- Added verification provenance and freshness metadata to `contracts.json` and its JSON Schema.
+- Aligned MCP, CLI, and Skills guidance with the official mainnet energy API default, public payer-history recovery, tokenless idempotent orders, exact signed-request persistence, the configured-wallet/no-argument payment-risk check, and the CLI's actual 30 top-level command groups.
+
 ### Added — 2026-05-22 API-style + reference-gap pass
 
 - **TronWeb call style unified across all developer pages.** Removed every `.methods.X()` (Web3.js-style) call from `developers/common_pitfalls.md` (10 occurrences) and `developers/supply_and_borrow_market/sbm.md` (admonition snippet) — now consistently using TronWeb 5.x direct style (`contract.method(args).call()` / `.send()`). Also dropped `.send({ from: addr })` (8 in common_pitfalls + 4 in sbm) in favor of the canonical TronWeb pattern of setting `tronWeb.defaultAddress` once. Both styles were technically supported, but the same file used both inconsistently. The `safeApprove` helper now throws early if `tronWeb.defaultAddress.base58` is unset (silent "no sender" failure was the most common confusion).

docs/ai_support/ai_llms.md

@@ -30,6 +30,8 @@ JustLend DAO provides machine-readable documentation endpoints optimized for LLM
 | Validating a copy of `contracts.json` (schema check) | [`contracts.schema.json`](../developers/contracts.schema.json) (JSON Schema 2020-12) |
 | Contract calls, event decoding, and agent tooling | [`developers/abis/`](../developers/abis/jtoken.json) |
 | MCP tool routing and safety annotations | [`MCP Tool Catalog`](../documents/aidocs/mcp_tools.md) |
+| Deterministic shell and CI automation | [JustLend CLI](cli_and_sdk.md#cli-deterministic-terminal-automation) |
+| Embedded V2 browser or Node.js integration | [JustLend V2 Utils](cli_and_sdk.md#v2-utils-embedded-application-integration) |
 
 
 ## AI Docs scoring and retrieval hints
@@ -43,7 +45,8 @@ The [`documents/aidocs`](../documents/aidocs/index.md) section is intentionally
 
 ## Notes for agents
 
-- Treat the OpenAPI spec, MCP tools, `contracts.json`, and ABI JSON files as machine-readable sources of truth.
+- Treat the OpenAPI spec, MCP tools, CLI JSON envelopes, `contracts.json`, and ABI JSON files as machine-readable sources of truth.
+- Use the [CLI and V2 SDK guide](cli_and_sdk.md) to choose between terminal automation and embedded integration, and inspect side effects before any signature or broadcast.
 - Treat rendered pages as human-readable explanations and examples.
 - Respect documented precision rules: jTokens use 8 decimals; underlying assets use their own decimals; rates and mantissas are scaled by `1e18`.
 - Use Nile testnet for integration testing and Mainnet only when users explicitly intend production transactions.

docs/ai_support/cli_and_sdk.md

@@ -0,0 +1,103 @@
+---
+title: JustLend CLI and V2 SDK
+description: Official source-installable JustLend CLI and V2 utility library for deterministic terminal automation and embedded TRON application integrations, with JSON, exit-code, signing, and safety guidance.
+tags:
+  - justlend
+  - cli
+  - sdk
+  - tronweb
+  - automation
+  - ai-support
+---
+
+# JustLend CLI and V2 SDK
+
+JustLend provides two source-distributed integration surfaces in addition to the HTTP API, MCP server, and Skills package:
+
+| Surface | Repository | Current version | Best for | Side effects |
+|---------|------------|-----------------|----------|--------------|
+| **JustLend CLI** | [`justlend/justlend-cli`](https://github.com/justlend/justlend-cli) | `1.0.1` | Deterministic terminal automation, CI jobs, dry-run transaction simulation, and machine-readable command output. | Mix of read-only and signing/broadcast commands; inspect the command class and simulate first. |
+| **JustLend V2 Utils** | [`justlend/justlend-utils-v2`](https://github.com/justlend/justlend-utils-v2) | `1.0.0` | Embedding V2 vault, lending, liquidation, mining, WTRX, and energy-purchase flows in browser or Node.js applications. | Many exported methods build, sign, or broadcast transactions through the injected `TronWeb` instance. |
+
+Neither project is currently published to npm. Install from the official GitHub source rather than guessing an npm package name.
+
+## CLI: deterministic terminal automation
+
+```bash
+git clone https://github.com/justlend/justlend-cli.git
+cd justlend-cli
+npm ci
+npm run build
+npm link
+justlend --help
+```
+
+The CLI exposes 30 top-level command groups covering V1 and V2 lending, vaults, account positions, liquidation, sTRX and stUSDT staking, WTRX, energy rental, governance, mining, rewards, history, portfolio analysis, and transaction simulation.
+
+### Agent contract
+
+- Add `--json` for exactly one machine-readable success or error envelope, including parser and usage failures. Do not parse colorized human tables.
+- Branch on the process exit code: `0` for success, non-zero for usage, validation, transport, simulation, signing, or broadcast failures.
+- Pin output schema major `1`: success is `{ schemaVersion: "1.0.0", success: true, data }`; failure is `{ schemaVersion, success: false, error, code, retryable, hint? }`.
+- Validate output with [`schemas/output-v1.schema.json`](https://github.com/justlend/justlend-cli/blob/main/schemas/output-v1.schema.json). Treat `retryable` as the retry signal; never blindly retry a write.
+- Use `--dry-run --dry-run-owner <address>` first. Dry-run simulates and never signs or broadcasts.
+- Use `--no-broadcast` for sign-only validation, then broadcast only after explicit human intent.
+- Energy direct purchase is the exception: it rejects `--no-broadcast` because the configured backend controls broadcast. Use `energy purchase quote` or `--dry-run` before the explicitly confirmed purchase instead.
+- Mainnet energy purchase uses the official `https://tegrow.ablesdxd.link` service by default. Nile requires an explicit matching custom `--energy-api-url`; the CLI rejects the production service on non-mainnet, including `buy --dry-run`.
+- Use `energy purchase history <payer>` to recover public in-progress/settled orders. An ambiguous result may retain the exact signed request in the local mode-`0600` risk file; it is redacted from output and blocks another payment until history reconciliation clears it.
+- In non-interactive or JSON mode, writes require `--yes`; that flag bypasses the local prompt and must not be added automatically.
+- Prefer `--network nile` for integration tests. Mainnet writes are irreversible.
+
+```bash
+# Read-only, machine-readable
+justlend --json --network mainnet market list
+
+# No signer and no broadcast
+justlend --json --network nile --dry-run \
+  --dry-run-owner TYourAddress... strx stake 0.000001
+```
+
+See the repository README for the complete command tree, response schema, retry policy, and side-effect classification.
+
+## V2 Utils: embedded application integration
+
+```bash
+npm install github:justlend/justlend-utils-v2
+# or: pnpm add github:justlend/justlend-utils-v2
+```
+
+Inject a ready `TronWeb` instance before calling contract helpers. In Node.js, also set the sender explicitly:
+
+```js
+import { TronWeb } from 'tronweb';
+import { tronObj } from 'justlend-v2-utils';
+
+const tronWeb = new TronWeb({
+  fullHost: 'https://nile.trongrid.io',
+  privateKey: process.env.PRIVATE_KEY,
+});
+
+tronObj.tronWeb = tronWeb;
+tronObj.defaultAccount = tronWeb.defaultAddress.base58;
+tronObj.network = 'nile';
+```
+
+### Agent safety rules
+
+1. Never invent contract addresses or market parameters. Resolve them from the live API, MCP tools, or [`contracts.json`](../developers/contracts.json).
+2. Preserve amounts as decimal strings or `BigNumber` values; do not route token amounts through JavaScript `number`.
+3. Inspect whether a helper is read-only or creates a transaction before calling it. `depositToVault`, `supplyCollateral`, `borrow`, `repay`, `liquidate`, `multiClaim`, and energy `purchase()` are write paths.
+4. Keep private keys, signed transactions, and wallet session material out of prompts, logs, and tool output.
+5. Use Nile and a non-production wallet for tests. Require explicit human confirmation immediately before a Mainnet signature or broadcast.
+6. For energy purchases, use the official service only on mainnet, configure a matching service on non-mainnet, and preserve durable payment-risk state; never fabricate pricing or payment-address fallbacks.
+
+## Which integration surface should an agent choose?
+
+| Need | Use |
+|------|-----|
+| Public read-only HTTP data | [OpenAPI](../developers/apis/justlend_apis.yaml) |
+| Wallet-aware agent tools with discoverable schemas | [Full MCP server](mcp_server.md) |
+| Read-only reusable agent instructions | [JustLend Skills](justlend_skills.md) |
+| Reproducible shell/CI automation | **JustLend CLI** |
+| Embedded browser or Node.js contract integration | **JustLend V2 Utils** |
+| Deployed addresses and ABI lookup | [`contracts.json`](../developers/contracts.json) + [JSON ABIs](../developers/abis/index.md) |

docs/ai_support/index.md

@@ -12,15 +12,16 @@ tags:
 
 # AI Support
 
-This section collects everything an AI agent or LLM tool needs to integrate with JustLend DAO: machine-readable documentation endpoints, the MCP server, JustLend Skills, and a compact AI/RAG documentation set.
+This section collects everything an AI agent or LLM tool needs to integrate with JustLend DAO: machine-readable documentation endpoints, the MCP server, JustLend Skills, the official CLI and V2 utility library, and a compact AI/RAG documentation set.
 
 ## In this section
 
 | Page | Use for |
 |------|---------|
 | [AI / LLMs](ai_llms.md) | Machine-readable entry points — [`llms.txt`](/llms.txt), [`llms-full.txt`](/llms-full.txt), OpenAPI YAML, `contracts.json`, JSON ABIs — and which to use when. |
-| [MCP Server](mcp_server.md) | Install and run the JustLend MCP server (98 tools): account analysis, market queries, transaction pre-flight, and wallet-aware writes with HITL confirmation. |
-| [JustLend Skills](justlend_skills.md) | The GitHub-distributed JustLend Skills project (9 read-only tools) for agent frameworks. |
+| [MCP Server](mcp_server.md) | Install and run the JustLend MCP server (104 tools): account analysis, market queries, transaction pre-flight, and wallet-aware writes with HITL confirmation. |
+| [JustLend Skills](justlend_skills.md) | Six workflow modules plus a bundled 9-tool read-only MCP server for agent frameworks. |
+| [CLI and V2 SDK](cli_and_sdk.md) | Source installation, versioning, JSON/exit-code contract, dry-run workflow, TronWeb injection, and write-safety rules. |
 | [AI Docs for Agents](../documents/aidocs/index.md) | Compact, RAG-oriented pages: source-of-truth routing, market/account/workflow guides, MCP safety policy, English/Chinese FAQs, and the full MCP tool catalog. |
 
 ## Machine-readable sources of truth
@@ -38,5 +39,7 @@ For task-by-task routing (e.g. "what markets exist", "this address's health fact
 
 - **Read-only HTTP integration** → OpenAPI spec / `/lend/*` endpoints.
 - **Agent workflows and wallet actions** → MCP server tools.
+- **Terminal / CI automation** → JustLend CLI with `--json` and exit-code checks.
+- **Embedded browser or Node.js integration** → JustLend V2 Utils with an explicitly injected `TronWeb` instance.
 - **Addresses and ABIs** → `contracts.json` + `/developers/abis/`.
 - **Concepts and risk context** → the human documentation pages.