diff --git a/README.md b/README.md index 1e9a59a..46081e5 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,15 @@ description: "AI Meets Bitcoin: Build, trade, explore, and govern—all on-chain." --- -[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aibtcdev/aibtcdev-docs) - -# AIBTC +# AIBTC Documentation -## AI DAOs: On-Chain Governance Without Permission +Welcome to the official documentation for AIBTC, the protocol for AI-governed DAOs on Bitcoin. -AI DAOs are autonomous entities that act, decide, and evolve based on community-driven logic. Token holders have immediate, actionable ways to shape their trajectory: +This documentation is organized into four main sections to help you find what you need quickly: -- Create Payable Services: Monetize features or services—payments flow directly to the treasury. -- Deposit Assets to Treasury: Secure capital in the DAO’s core financial engine. -- Propose Treasury Spending: Drive growth, fund partnerships, or launch community initiatives. -- Set Withdrawal Rules: Establish how often and how much can be withdrawn from the timed vault. -- Vote on Proposals: Influence treasury use, governance updates, and new initiatives. -- Modify Contracts: Expand functionality by proposing and approving new smart contracts. -- Assign Roles: Empower agents with defined responsibilities. -- Adjust DAO Parameters: Refine rules—voting thresholds, quorums, treasury settings. +- **[Tutorials](./docs/tutorials/launch-first-dao.md)**: Get started with a hands-on, step-by-step guide to launching your first AI DAO. +- **[How-To Guides](./docs/how-to-guides/README.md)**: Find short, focused articles on how to perform specific tasks. +- **[Explanation](./docs/explanation/README.md)**: Dive deep into the core concepts and architecture of the AIBTC protocol. +- **[Reference](./docs/reference/README.md)**: Look up detailed technical information on smart contracts, APIs, and agent tools. -> **Why It Matters:** AI DAOs enable immediate, meaningful participation. Holders don’t just vote—they execute change. - -This framework launches with both security and adaptability in mind, giving the DAO collective control over its treasury and governance right from the start. +[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/aibtcdev/aibtcdev-docs) diff --git a/SUMMARY.md b/SUMMARY.md index b03553d..a50dd6a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,73 +1,58 @@ # Table of contents - [AIBTC](README.md) -- [Prompt2DAO](introduction/prompt2dao.md) -## AIBTC Contracts - -- [DAO Base Layer](aibtc-contracts/dao-base-layer.md) -- [DAO Extensions](aibtc-contracts/dao-extensions/README.md) - - [Action Proposal Voting](aibtc-contracts/dao-extensions/action-proposal-voting.md) - - [DAO Charter](aibtc-contracts/dao-extensions/dao-charter.md) - - [DAO Epoch](aibtc-contracts/dao-extensions/dao-epoch.md) - - [DAO Users](aibtc-contracts/dao-extensions/dao-users.md) - - [Onchain Messaging](aibtc-contracts/dao-extensions/onchain-messaging.md) - - [Rewards Account](aibtc-contracts/dao-extensions/rewards-account.md) - - [Token Owner](aibtc-contracts/dao-extensions/token-owner.md) - - [Treasury](aibtc-contracts/dao-extensions/treasury.md) -- [DAO Proposals](aibtc-contracts/dao-proposals/README.md) - - [Action Proposals](aibtc-contracts/dao-proposals/action-proposals.md) -- [Agent Account](aibtc-contracts/agent-account/README.md) - -## Agent Tools - -- [Overview](agent-tools/README.md) -- [Available Tools](agent-tools/available-tools/README.md) - - [Agent Account Tools](agent-tools/available-tools/agentaccount-tools.md) - - [Agent Wallet Tools](agent-tools/available-tools/wallet-tools.md) - - [DAO Tools](agent-tools/available-tools/dao-tools.md) - - [Database Tools](agent-tools/available-tools/database-tools.md) - - [Faktory Tools](agent-tools/available-tools/faktory-tools.md) - -## AIBTC Cache - -- [Overview](aibtc-cache/README.md) -- [Contract Calls](aibtc-cache/contract-calls/README.md) - - [API Design](aibtc-cache/contract-calls/api-design.md) - - [Endpoints](aibtc-cache/contract-calls/endpoints/README.md) - - [Decode Clarity Value](aibtc-cache/contract-calls/endpoints/decode-clarity-value.md) - - [Read-Only Function Calls](aibtc-cache/contract-calls/endpoints/read-only-calls.md) - - [Contract ABI](aibtc-cache/contract-calls/endpoints/contract-abi.md) - - [Known ABI Contracts](aibtc-cache/contract-calls/endpoints/known-contracts.md) - - [Clarity Value Types](aibtc-cache/contract-calls/clarity-value-types.md) - - [Integration Examples](aibtc-cache/contract-calls/integration-examples.md) -- [Cache Services](aibtc-cache/cache-services.md) -- [Error Handling](aibtc-cache/error-handling.md) -- [Utilities](aibtc-cache/utilities.md) - -## Links - -- [Common Terms](introduction/common-terms.md) -- [Our App](https://aibtc.dev) -- [Discord](https://discord.gg/Z59Z3FNbEX) -- [GitHub](https://github.com/aibtcdev) -- [Prompt2DAO on X](https://x.com/prompt2dao) -- [AIBTC on X](https://x.com/aibtcdev) - -## Templates - -- [Template Style Guide](template-style-guide.md) - -### Documentation Templates - -- [Smart Contract Documentation](templates/smart-contract-documentation.md) -- [Cache Service Documentation](templates/cache-service-documentation.md) -- [Cache Endpoint Documentation](templates/cache-endpoint-documentation.md) -- [Agent Tool Documentation](templates/agent-tool-documentation.md) - -### Example Implementations - -- [Agent Account Example](templates/agent-account-example.md) -- [Cache Service Example](templates/cache-service-example.md) -- [Cache Endpoint Example](templates/cache-endpoint-example.md) -- [Agent Tool Example](templates/agent-tool-example.md) +## Getting Started + +- [Tutorial: Launch Your First AI DAO](docs/tutorials/launch-first-dao.md) + +## Explanation + +- [Overview](docs/explanation/README.md) +- [Core Concepts](docs/explanation/core-concepts.md) +- [Prompt2DAO](docs/explanation/prompt2dao.md) +- [Common Terms](docs/explanation/common-terms.md) + +## How-To Guides + +- [Overview](docs/how-to-guides/README.md) +- [Create an Agent Account](docs/how-to-guides/create-agent-account.md) +- [Propose an Action](docs/how-to-guides/propose-action.md) + +## Reference + +- [Overview](docs/reference/README.md) +- [Smart Contracts](docs/reference/smart-contracts/README.md) + - [DAO Base Layer](docs/reference/smart-contracts/dao-base-layer.md) + - [DAO Extensions](docs/reference/smart-contracts/dao-extensions/README.md) + - [Action Proposal Voting](docs/reference/smart-contracts/dao-extensions/action-proposal-voting.md) + - [DAO Charter](docs/reference/smart-contracts/dao-extensions/dao-charter.md) + - [DAO Epoch](docs/reference/smart-contracts/dao-extensions/dao-epoch.md) + - [DAO Users](docs/reference/smart-contracts/dao-extensions/dao-users.md) + - [Onchain Messaging](docs/reference/smart-contracts/dao-extensions/onchain-messaging.md) + - [Rewards Account](docs/reference/smart-contracts/dao-extensions/rewards-account.md) + - [Token Owner](docs/reference/smart-contracts/dao-extensions/token-owner.md) + - [Treasury](docs/reference/smart-contracts/dao-extensions/treasury.md) + - [DAO Proposals](docs/reference/smart-contracts/dao-proposals/README.md) + - [Action Proposals](docs/reference/smart-contracts/dao-proposals/action-proposals.md) + - [Agent Account](docs/reference/smart-contracts/agent-account/README.md) +- [Agent Tools](docs/reference/agent-tools/README.md) + - [Available Tools](docs/reference/agent-tools/available-tools/README.md) + - [Agent Account Tools](docs/reference/agent-tools/available-tools/agentaccount-tools.md) + - [Agent Wallet Tools](docs/reference/agent-tools/available-tools/wallet-tools.md) + - [DAO Tools](docs/reference/agent-tools/available-tools/dao-tools.md) + - [Database Tools](docs/reference/agent-tools/available-tools/database-tools.md) + - [Faktory Tools](docs/reference/agent-tools/available-tools/faktory-tools.md) +- [Cache API](docs/reference/cache-api/README.md) + - [Contract Calls](docs/reference/cache-api/contract-calls/README.md) + - [API Design](docs/reference/cache-api/contract-calls/api-design.md) + - [Endpoints](docs/reference/cache-api/contract-calls/endpoints/README.md) + - [Decode Clarity Value](docs/reference/cache-api/contract-calls/endpoints/decode-clarity-value.md) + - [Read-Only Function Calls](docs/reference/cache-api/contract-calls/endpoints/read-only-calls.md) + - [Contract ABI](docs/reference/cache-api/contract-calls/endpoints/contract-abi.md) + - [Known ABI Contracts](docs/reference/cache-api/contract-calls/endpoints/known-contracts.md) + - [Clarity Value Types](docs/reference/cache-api/contract-calls/clarity-value-types.md) + - [Integration Examples](docs/reference/cache-api/contract-calls/integration-examples.md) + - [Cache Services](docs/reference/cache-api/cache-services.md) + - [Error Handling](docs/reference/cache-api/error-handling.md) + - [Utilities](docs/reference/cache-api/utilities.md) diff --git a/agent-tools/README.md b/agent-tools/README.md deleted file mode 100644 index 86f804c..0000000 --- a/agent-tools/README.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -description: Overview of the agent tools system ---- - -# Agent Tools - -Agent tools are modular components that provide specific functionality to AI agents. They allow agents to interact with blockchain networks, manage wallets, interact with DAOs, and perform various other tasks. - -## How Agent Tools Work - -Each tool: - -- Has a specific purpose and functionality -- Can be enabled or disabled for specific agents -- Has clear input and output specifications -- Provides error handling and feedback - -## Tool Architecture - -Tools follow a consistent pattern: - -1. **Input Schema**: Each tool has a defined input schema using Pydantic models -2. **Execution Logic**: Tools contain the logic to perform their specific function -3. **Error Handling**: Tools provide standardized error responses -4. **Return Values**: Tools return structured data that can be parsed by agents - -### Useful Debugging Techniques - -When working with tools, these prompting patterns can help with debugging: - -- **Get transaction details** - - ``` - Get the details for the TXID 0x3cc19a5aa3ba3af9e14716e3a988de748b9bc034efd4fa13f7d30c00a901ff9f and from those details, tell me the proposal ID and voting period. - ``` - -- **Request detailed error information** - - ``` - If you run into an error post the detailed inputs and outputs from the tool so we can debug. - ``` - -- **Get transaction history for an address** - - ``` - Tell me more about the last 5 transactions sent by ST43FFM04WT907DE9EXHQPBG3BW7R6R7R6RXZV6C - ``` - -- **Get contract transaction history** - ``` - Tell me more about last 5 transactions in the contract ST3YT0XW92E6T2FE59B2G5N2WNNFSBZ6MZKQS5D18.faces-action-proposals-v2 - ``` - -## Tool Security - -Tools follow these security principles: - -- Tools verify caller permissions where necessary -- Critical operations require explicit confirmation -- Tools use standardized error handling -- Tools emit detailed logs for auditing purposes - -For detailed documentation on each tool category, see the individual tool pages. - -## Related Repositories - -The agent tools system is built on two key repositories: - -### agent-tools-ts - -[agent-tools-ts](https://github.com/aibtcdev/agent-tools-ts) contains the TypeScript implementation of the agent tools, powered by Bun and Stacks.js. This repository provides: - -- Low-level blockchain interactions -- Wallet management utilities -- Smart contract interactions -- TypeScript interfaces and implementations -- Command-line tools for testing and development - -### aibtcdev-backend - -[aibtcdev-backend](https://github.com/aibtcdev/aibtcdev-backend) is the Python backend service that exposes these tools to LLM agents. This repository includes: - -- Python wrappers for the TypeScript tools -- FastAPI endpoints for agent interactions -- LangGraph integration for agent workflows -- Background task scheduling -- Database abstractions and models -- Webhook handling for blockchain events diff --git a/aibtc-cache/README.md b/aibtc-cache/README.md deleted file mode 100644 index 7837152..0000000 --- a/aibtc-cache/README.md +++ /dev/null @@ -1,123 +0,0 @@ -# AIBTC Cache Services - -The AIBTC Cache is a Cloudflare Workers-based caching layer that provides efficient access to blockchain data and other services. It helps reduce API rate limits, improve performance, and enhance reliability for applications in the AIBTC ecosystem. - -## Environments - -The cache service is available at the following URLs: - -- **Production**: [https://cache.aibtc.dev](https://cache.aibtc.dev) (main branch) -- **Staging**: [https://cache-staging.aibtc.dev](https://cache-staging.aibtc.dev) (staging branch) -- **Preview**: Preview URLs are generated for each PR and change with each deployment (e.g., `https://aibtcdev-cache-preview.hosting-962.workers.dev/`) - -## Key Components - -- **Durable Objects**: Stateful components that handle specific API caching needs -- **Rate Limiting**: Intelligent rate limiting to prevent exceeding external API quotas -- **Caching**: KV-based caching with configurable TTLs -- **Request Queuing**: Orderly processing of requests with automatic retries -- **[Error Handling](error-handling.md)**: Standardized error responses with detailed information -- **Logging**: Comprehensive logging with performance tracking - -## Available Services - -The cache currently supports the following services: - -- [Contract Calls](/aibtc-cache/contract-calls/README.md) - For interacting with Stacks smart contracts - -## Architecture - -The cache uses a multi-layered approach: - -1. **Request Layer**: Handles incoming requests and routes them to appropriate Durable Objects -2. **Durable Object Layer**: Maintains state and handles service-specific logic -3. **Service Layer**: Provides reusable services for API interactions, caching, and rate limiting -4. **Utility Layer**: Common utilities for request/response handling and data transformation - -## Response Format - -All API responses follow a standardized format: - -### Success Response - -```json -{ - "success": true, - "data": { - // The actual response data - } -} -``` - -### Error Response - -```json -{ - "success": false, - "error": { - "id": "unique-error-id", - "code": "ERROR_CODE", - "message": "Human-readable error message", - "details": { - // Optional additional error details - } - } -} -``` - -## Getting Started - -To use the cache in your application, make requests to the appropriate endpoints. See the service-specific documentation for details on available endpoints and request formats. - -### Example: Calling a read-only function - -```javascript -// Example: Call get-proposal function -fetch( - "https://cache.aibtc.dev/contract-calls/read-only/ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA/media3-action-proposals-v2/get-proposal", - { - method: "POST", - headers: { - "Content-Type": "application/json", - }, - body: JSON.stringify({ - functionArgs: [ - { - type: "uint", - value: "3", - }, - ], - network: "testnet", - cacheControl: { - bustCache: false, // Use cached value if available - ttl: 3600 // Cache for 1 hour - } - }), - } -) - .then((response) => response.json()) - .then((result) => { - if (result.success) { - console.log("Proposal data:", result.data); - } else { - console.error("Error:", result.error); - } - }); -``` - -### Example: Fetching a contract ABI - -```javascript -// Example: Fetch the ABI for media3-core-proposals-v2 -fetch( - "https://cache.aibtc.dev/contract-calls/abi/ST252TFQ08T74ZZ6XK426TQNV4EXF1D4RMTTNCWFA/media3-core-proposals-v2" -) - .then((response) => response.json()) - .then((result) => { - if (result.success) { - console.log("Contract ABI:", result.data); - } else { - console.error("Error:", result.error); - } - }); -``` diff --git a/docs/explanation/README.md b/docs/explanation/README.md new file mode 100644 index 0000000..691e327 --- /dev/null +++ b/docs/explanation/README.md @@ -0,0 +1,7 @@ +--- +description: High-level explanations of AIBTC's architecture and core ideas. +--- + +# Explanation + +This section provides high-level explanations of the core concepts, architecture, and vision behind AIBTC. It's designed to give you the context you need to understand why the protocol is built the way it is. diff --git a/introduction/common-terms.md b/docs/explanation/common-terms.md similarity index 100% rename from introduction/common-terms.md rename to docs/explanation/common-terms.md diff --git a/docs/explanation/core-concepts.md b/docs/explanation/core-concepts.md new file mode 100644 index 0000000..6f5434c --- /dev/null +++ b/docs/explanation/core-concepts.md @@ -0,0 +1,22 @@ +--- +description: The core concepts behind AIBTC and AI DAOs. +--- + +# Core Concepts + +## AI DAOs: On-Chain Governance Without Permission + +AI DAOs are autonomous entities that act, decide, and evolve based on community-driven logic. Token holders have immediate, actionable ways to shape their trajectory: + +- Create Payable Services: Monetize features or services—payments flow directly to the treasury. +- Deposit Assets to Treasury: Secure capital in the DAO’s core financial engine. +- Propose Treasury Spending: Drive growth, fund partnerships, or launch community initiatives. +- Set Withdrawal Rules: Establish how often and how much can be withdrawn from the timed vault. +- Vote on Proposals: Influence treasury use, governance updates, and new initiatives. +- Modify Contracts: Expand functionality by proposing and approving new smart contracts. +- Assign Roles: Empower agents with defined responsibilities. +- Adjust DAO Parameters: Refine rules—voting thresholds, quorums, treasury settings. + +> **Why It Matters:** AI DAOs enable immediate, meaningful participation. Holders don’t just vote—they execute change. + +This framework launches with both security and adaptability in mind, giving the DAO collective control over its treasury and governance right from the start. diff --git a/introduction/prompt2dao.md b/docs/explanation/prompt2dao.md similarity index 100% rename from introduction/prompt2dao.md rename to docs/explanation/prompt2dao.md diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md new file mode 100644 index 0000000..c6460d6 --- /dev/null +++ b/docs/how-to-guides/README.md @@ -0,0 +1,7 @@ +--- +description: Step-by-step guides for common tasks in AIBTC. +--- + +# How-To Guides + +This section provides practical, step-by-step guides to help you accomplish specific tasks with the AIBTC protocol. diff --git a/docs/how-to-guides/create-agent-account.md b/docs/how-to-guides/create-agent-account.md new file mode 100644 index 0000000..0f8ae4c --- /dev/null +++ b/docs/how-to-guides/create-agent-account.md @@ -0,0 +1,7 @@ +--- +description: A step-by-step guide on how to create an agent account. +--- + +# How-To: Create an Agent Account + +(Content to be added) diff --git a/docs/how-to-guides/propose-action.md b/docs/how-to-guides/propose-action.md new file mode 100644 index 0000000..b6bae45 --- /dev/null +++ b/docs/how-to-guides/propose-action.md @@ -0,0 +1,7 @@ +--- +description: A step-by-step guide on how to propose an action within a DAO. +--- + +# How-To: Propose an Action + +(Content to be added) diff --git a/docs/reference/README.md b/docs/reference/README.md new file mode 100644 index 0000000..6131f7a --- /dev/null +++ b/docs/reference/README.md @@ -0,0 +1,7 @@ +--- +description: Technical reference documentation for the AIBTC protocol. +--- + +# Reference + +This section contains detailed technical reference material for all components of the AIBTC protocol, including smart contracts, APIs, and agent tools. diff --git a/agent-tools/available-tools/README.md b/docs/reference/agent-tools/available-tools/README.md similarity index 100% rename from agent-tools/available-tools/README.md rename to docs/reference/agent-tools/available-tools/README.md diff --git a/agent-tools/available-tools/agentaccount-tools.md b/docs/reference/agent-tools/available-tools/agentaccount-tools.md similarity index 100% rename from agent-tools/available-tools/agentaccount-tools.md rename to docs/reference/agent-tools/available-tools/agentaccount-tools.md diff --git a/agent-tools/available-tools/dao-tools.md b/docs/reference/agent-tools/available-tools/dao-tools.md similarity index 100% rename from agent-tools/available-tools/dao-tools.md rename to docs/reference/agent-tools/available-tools/dao-tools.md diff --git a/agent-tools/available-tools/database-tools.md b/docs/reference/agent-tools/available-tools/database-tools.md similarity index 100% rename from agent-tools/available-tools/database-tools.md rename to docs/reference/agent-tools/available-tools/database-tools.md diff --git a/agent-tools/available-tools/faktory-tools.md b/docs/reference/agent-tools/available-tools/faktory-tools.md similarity index 100% rename from agent-tools/available-tools/faktory-tools.md rename to docs/reference/agent-tools/available-tools/faktory-tools.md diff --git a/agent-tools/available-tools/wallet-tools.md b/docs/reference/agent-tools/available-tools/wallet-tools.md similarity index 100% rename from agent-tools/available-tools/wallet-tools.md rename to docs/reference/agent-tools/available-tools/wallet-tools.md diff --git a/aibtc-cache/cache-services.md b/docs/reference/cache-api/cache-services.md similarity index 100% rename from aibtc-cache/cache-services.md rename to docs/reference/cache-api/cache-services.md diff --git a/aibtc-cache/contract-calls/README.md b/docs/reference/cache-api/contract-calls/README.md similarity index 100% rename from aibtc-cache/contract-calls/README.md rename to docs/reference/cache-api/contract-calls/README.md diff --git a/aibtc-cache/contract-calls/api-design.md b/docs/reference/cache-api/contract-calls/api-design.md similarity index 100% rename from aibtc-cache/contract-calls/api-design.md rename to docs/reference/cache-api/contract-calls/api-design.md diff --git a/aibtc-cache/contract-calls/clarity-value-types.md b/docs/reference/cache-api/contract-calls/clarity-value-types.md similarity index 100% rename from aibtc-cache/contract-calls/clarity-value-types.md rename to docs/reference/cache-api/contract-calls/clarity-value-types.md diff --git a/aibtc-cache/contract-calls/endpoints/README.md b/docs/reference/cache-api/contract-calls/endpoints/README.md similarity index 100% rename from aibtc-cache/contract-calls/endpoints/README.md rename to docs/reference/cache-api/contract-calls/endpoints/README.md diff --git a/aibtc-cache/contract-calls/endpoints/contract-abi.md b/docs/reference/cache-api/contract-calls/endpoints/contract-abi.md similarity index 100% rename from aibtc-cache/contract-calls/endpoints/contract-abi.md rename to docs/reference/cache-api/contract-calls/endpoints/contract-abi.md diff --git a/aibtc-cache/contract-calls/endpoints/decode-clarity-value.md b/docs/reference/cache-api/contract-calls/endpoints/decode-clarity-value.md similarity index 100% rename from aibtc-cache/contract-calls/endpoints/decode-clarity-value.md rename to docs/reference/cache-api/contract-calls/endpoints/decode-clarity-value.md diff --git a/aibtc-cache/contract-calls/endpoints/known-contracts.md b/docs/reference/cache-api/contract-calls/endpoints/known-contracts.md similarity index 100% rename from aibtc-cache/contract-calls/endpoints/known-contracts.md rename to docs/reference/cache-api/contract-calls/endpoints/known-contracts.md diff --git a/aibtc-cache/contract-calls/endpoints/read-only-calls.md b/docs/reference/cache-api/contract-calls/endpoints/read-only-calls.md similarity index 100% rename from aibtc-cache/contract-calls/endpoints/read-only-calls.md rename to docs/reference/cache-api/contract-calls/endpoints/read-only-calls.md diff --git a/aibtc-cache/contract-calls/integration-examples.md b/docs/reference/cache-api/contract-calls/integration-examples.md similarity index 100% rename from aibtc-cache/contract-calls/integration-examples.md rename to docs/reference/cache-api/contract-calls/integration-examples.md diff --git a/aibtc-cache/error-handling.md b/docs/reference/cache-api/error-handling.md similarity index 100% rename from aibtc-cache/error-handling.md rename to docs/reference/cache-api/error-handling.md diff --git a/aibtc-cache/utilities.md b/docs/reference/cache-api/utilities.md similarity index 100% rename from aibtc-cache/utilities.md rename to docs/reference/cache-api/utilities.md diff --git a/docs/reference/smart-contracts/README.md b/docs/reference/smart-contracts/README.md new file mode 100644 index 0000000..e364529 --- /dev/null +++ b/docs/reference/smart-contracts/README.md @@ -0,0 +1,7 @@ +--- +description: Technical reference for all AIBTC smart contracts. +--- + +# Smart Contracts Reference + +This section contains the detailed technical reference documentation for every smart contract in the AIBTC protocol. diff --git a/aibtc-contracts/agent-account/README.md b/docs/reference/smart-contracts/agent-account/README.md similarity index 100% rename from aibtc-contracts/agent-account/README.md rename to docs/reference/smart-contracts/agent-account/README.md diff --git a/aibtc-contracts/dao-base-layer.md b/docs/reference/smart-contracts/dao-base-layer.md similarity index 100% rename from aibtc-contracts/dao-base-layer.md rename to docs/reference/smart-contracts/dao-base-layer.md diff --git a/aibtc-contracts/dao-extensions/README.md b/docs/reference/smart-contracts/dao-extensions/README.md similarity index 100% rename from aibtc-contracts/dao-extensions/README.md rename to docs/reference/smart-contracts/dao-extensions/README.md diff --git a/aibtc-contracts/dao-extensions/action-proposal-voting.md b/docs/reference/smart-contracts/dao-extensions/action-proposal-voting.md similarity index 100% rename from aibtc-contracts/dao-extensions/action-proposal-voting.md rename to docs/reference/smart-contracts/dao-extensions/action-proposal-voting.md diff --git a/aibtc-contracts/dao-extensions/dao-charter.md b/docs/reference/smart-contracts/dao-extensions/dao-charter.md similarity index 100% rename from aibtc-contracts/dao-extensions/dao-charter.md rename to docs/reference/smart-contracts/dao-extensions/dao-charter.md diff --git a/aibtc-contracts/dao-extensions/dao-epoch.md b/docs/reference/smart-contracts/dao-extensions/dao-epoch.md similarity index 100% rename from aibtc-contracts/dao-extensions/dao-epoch.md rename to docs/reference/smart-contracts/dao-extensions/dao-epoch.md diff --git a/aibtc-contracts/dao-extensions/dao-users.md b/docs/reference/smart-contracts/dao-extensions/dao-users.md similarity index 100% rename from aibtc-contracts/dao-extensions/dao-users.md rename to docs/reference/smart-contracts/dao-extensions/dao-users.md diff --git a/aibtc-contracts/dao-extensions/onchain-messaging.md b/docs/reference/smart-contracts/dao-extensions/onchain-messaging.md similarity index 100% rename from aibtc-contracts/dao-extensions/onchain-messaging.md rename to docs/reference/smart-contracts/dao-extensions/onchain-messaging.md diff --git a/aibtc-contracts/dao-extensions/rewards-account.md b/docs/reference/smart-contracts/dao-extensions/rewards-account.md similarity index 100% rename from aibtc-contracts/dao-extensions/rewards-account.md rename to docs/reference/smart-contracts/dao-extensions/rewards-account.md diff --git a/aibtc-contracts/dao-extensions/token-owner.md b/docs/reference/smart-contracts/dao-extensions/token-owner.md similarity index 100% rename from aibtc-contracts/dao-extensions/token-owner.md rename to docs/reference/smart-contracts/dao-extensions/token-owner.md diff --git a/aibtc-contracts/dao-extensions/treasury.md b/docs/reference/smart-contracts/dao-extensions/treasury.md similarity index 100% rename from aibtc-contracts/dao-extensions/treasury.md rename to docs/reference/smart-contracts/dao-extensions/treasury.md diff --git a/aibtc-contracts/dao-proposals/README.md b/docs/reference/smart-contracts/dao-proposals/README.md similarity index 100% rename from aibtc-contracts/dao-proposals/README.md rename to docs/reference/smart-contracts/dao-proposals/README.md diff --git a/aibtc-contracts/dao-proposals/action-proposals.md b/docs/reference/smart-contracts/dao-proposals/action-proposals.md similarity index 100% rename from aibtc-contracts/dao-proposals/action-proposals.md rename to docs/reference/smart-contracts/dao-proposals/action-proposals.md diff --git a/docs/tutorials/launch-first-dao.md b/docs/tutorials/launch-first-dao.md new file mode 100644 index 0000000..79d6463 --- /dev/null +++ b/docs/tutorials/launch-first-dao.md @@ -0,0 +1,7 @@ +--- +description: A step-by-step tutorial to launch your first AI-powered DAO. +--- + +# Tutorial: Launch Your First AI DAO + +(Content to be added) diff --git a/template-style-guide.md b/template-style-guide.md index 9842ea1..e5d714d 100644 --- a/template-style-guide.md +++ b/template-style-guide.md @@ -14,6 +14,24 @@ This style guide provides guidelines for maintaining consistency, readability, a - **Accessibility**: Make documentation approachable for all skill levels - **Maintainability**: Structure content to be easily updated +## Documentation Categories + +Our documentation is organized into four categories based on user goals. When creating or updating documentation, ensure it fits into one of these categories: + +1. **Tutorials**: Learning-oriented guides designed to get a developer from zero to a first successful outcome. +2. **How-To Guides**: Goal-oriented "recipes" that provide step-by-step instructions to solve a specific problem. +3. **Reference**: Information-oriented technical descriptions of the system and its components (APIs, contracts, etc.). +4. **Explanation**: Understanding-oriented discussions that clarify high-level concepts and design decisions. + +## Rules for Automated Documentation Auditing + +To ensure documentation stays synchronized with the source code, an AI agent can perform audits based on the following rules: + +- **Rule 1 (File Mapping):** Source code artifacts map directly to documentation files in the `docs/reference/` directory. A change in a source file implies its corresponding documentation file needs review. + - Example: A change in `aibtc-contracts/dao-extensions/dao-charter.md` requires a review of `docs/reference/smart-contracts/dao-extensions/dao-charter.md`. +- **Rule 2 (Metadata):** The YAML frontmatter in each reference document is critical for tracking. The `version` property in the documentation must correspond to the version of the contract or tool it documents. +- **Rule 3 (Template Usage):** When creating a new reference document, the appropriate template from the `/templates` directory must be used to ensure all required machine-readable fields are present. + ## Document Structure Standards ### Required Elements diff --git a/templates/smart-contract-documentation.md b/templates/smart-contract-documentation.md index 8b94a66..4cd44a1 100644 --- a/templates/smart-contract-documentation.md +++ b/templates/smart-contract-documentation.md @@ -125,6 +125,10 @@ flowchart TD - **[Security Feature 2]**: [Explanation] - **[Security Risk 1]**: [Explanation and mitigation] +## Related How-To Guides + +- **[How to Propose a Vote]**: [Link to the relevant how-to guide] + ## Related Contracts - **[Related Contract 1]**: [Brief description of relationship]