Add complete Neutron documentation structure

README.md

@@ -1,41 +1,108 @@
-# Website
+# Neutron Documentation
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+The comprehensive documentation hub for the Neutron blockchain - the first Consumer Chain of the Cosmos Hub. This repository contains detailed guides, tutorials, and references for developers, validators, and users of the Neutron ecosystem.
 
-### Installation
+## 🌟 What is Neutron?
 
-```
-$ yarn
-```
+Neutron is a permissionless smart contract platform that leverages Interchain Security (ICS) from Cosmos Hub, enabling secure cross-chain DeFi applications with native integrations to 50+ Cosmos chains and beyond.
+
+## 📖 Documentation Structure
+
+### 🏠 **Home & Core Concepts**
+- **Introduction & Quickstart**: Get started with Neutron basics
+- **Integrated Architecture**: Understanding Neutron's unique Consumer Chain design
+- **Opinionated Blockchains**: How Neutron enables focused blockchain applications
+- **Proof of Liquid Staking**: Neutron's innovative consensus and security model
+- **Modular Governance**: Decentralized decision-making mechanisms
+- **Tokenomics**: NTRN token economics and utility
+
+### 💹 **DeFi Ecosystem**
+- **DeFi Overview**: Complete landscape of Neutron's financial applications
+- **Featured Protocols**: Duality, SuperVaults, Bull vs Bear, Drop Staking
+- **Integration Guides**: How to connect with Neutron's DeFi infrastructure
+
+### 👨‍💻 **Developer Resources**
+- **Getting Started**: Developer onboarding and environment setup
+- **SDK & Tools**: Neutron Template, BullBear integration, boilerplates
+- **Comprehensive Tutorials**: 
+  - CosmWasm smart contract development
+  - Interchain Accounts (ICA) and Queries (ICQ)
+  - Integration testing and deployment
+  - Indexing and data analysis
+- **Modules Documentation**: Deep dives into Neutron's custom modules
+- **API Reference**: Complete technical specifications
+
+### 🔒 **Validator Operations**
+- **Overview**: Complete validator ecosystem and requirements
+- **Node Setup**: Comprehensive guide for running Neutron nodes
+- **Becoming a Validator**: Step-by-step validator registration process
+- **Oracle Operations**: Slinky oracle setup and maintenance
+- **Economics**: Validator incentives, rewards, and performance metrics
+- **Security**: Best practices and operational guidelines
+
+## 🛠 Development
+
+This documentation is built with [Mintlify](https://mintlify.com), a modern documentation platform designed for developer-focused content.
 
 ### Local Development
 
-```
-$ yarn start
-```
+1. **Install Mintlify CLI**:
+   ```bash
+   npm i -g mintlify
+   ```
+
+2. **Preview documentation locally**:
+   ```bash
+   mintlify dev
+   ```
+
+3. **Install dependencies** (if needed):
+   ```bash
+   mintlify install
+   ```
+
+### Publishing Changes
+
+Documentation is automatically deployed when changes are pushed to the default branch. For more information about Mintlify's deployment process, visit the [Mintlify documentation](https://mintlify.com/docs).
+
+### Troubleshooting
+
+- **Mintlify dev isn't running**: Run `mintlify install` to re-install dependencies
+- **Page loads as a 404**: Make sure you are running in a folder with `docs.json`
+- **Build errors**: Check the [Mintlify troubleshooting guide](https://mintlify.com/docs/troubleshooting)
+
+### Key Features
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+- 🎨 **Beautiful Design**: Modern, responsive interface with dark/light modes
+- 🔍 **Advanced Search**: Full-text search across all documentation
+- 📱 **Mobile Optimized**: Perfect experience on all devices
+- 🔗 **Deep Linking**: Direct links to specific sections and code blocks
+- 💻 **Code Examples**: Interactive code samples and tutorials
+- 🌐 **Multi-format Support**: MDX, API references, and rich media
 
-### Build
+## 🌐 Community & Resources
 
-```
-$ yarn build
-```
+### Official Links
+- **Website**: [neutron.org](https://neutron.org)
+- **App**: [app.neutron.org](https://app.neutron.org)
+- **GitHub**: [github.com/neutron-org](https://github.com/neutron-org)
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+### Community
+- **Discord**: [Join our community](https://discord.com/invite/bzPBzbDvWC)
+- **Twitter**: [@neutron_org](https://twitter.com/neutron_org)
+- **Forum**: [Neutron Governance](https://forum.neutron.org)
 
-### Deployment
+## 📊 Repository Statistics
 
-Using SSH:
+- **Comprehensive Coverage**: 100+ documentation pages
+- **Multi-audience**: Developers, validators, and end users
+- **Active Maintenance**: Regular updates with protocol developments
+- **Community Driven**: Open source with community contributions
 
-```
-$ USE_SSH=true yarn deploy
-```
+## 📝 License
 
-Not using SSH:
+This documentation is open source and available under the [MIT License](LICENSE).
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
+---
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+*Neutron: Secure, interoperable, and developer-friendly blockchain infrastructure for the next generation of DeFi.*

concepts/integrated-architecture.mdx

@@ -0,0 +1,97 @@
+---
+title: "Integrated Architecture"
+description: "How Neutron's DeFi-focused infrastructure combines app-specific features with atomic composability"
+icon: "puzzle-piece"
+---
+
+Neutron implements an integrated blockchain architecture that combines critical DeFi infrastructure directly at the protocol layer. This design ensures guaranteed execution, native cross-chain communication, atomic composability, and predictable performance—creating a shared environment where DeFi protocols benefit from specialized infrastructure without sacrificing interoperability.
+
+## Core Infrastructure Components
+
+<CardGroup cols={2}>
+  <Card title="Oracle Module" icon="bolt" iconType="duotone" href="/developers/modules/oracle">
+    Native price feeds updated every block with hardware-based security, eliminating dependence on external oracles and providing superior execution guarantees.
+  </Card>
+  <Card title="Interchain Queries (ICQ)" icon="network-wired" iconType="duotone" href="/developers/modules/interchain-queries">
+    Direct state queries across any IBC-connected chain, enabling real-time cross-chain data access without trusted third parties.
+  </Card>
+  <Card title="Cron Module" icon="clock" iconType="duotone" href="/developers/modules/cron">
+    Native automation allowing scheduled and conditional contract execution with protocol-level reliability.
+  </Card>
+  <Card title="Interchain Accounts" icon="arrows-left-right" iconType="duotone" href="/developers/tutorials/cosmwasm_ica">
+    Built-in interchain account functionality enabling seamless cross-chain operations with consensus-enforced security.
+  </Card>
+</CardGroup>
+
+This approach essentially provides infrastructure as a service at the protocol level, allowing all applications to leverage shared utilities without building duplicate systems or relying on external providers.
+
+## Benefits of Integration
+
+<CardGroup cols={2}>
+  <Card title="Capital Efficiency" icon="coins" iconType="duotone">
+    <ul className="mt-2 space-y-1">
+      <li>Optimized liquidity utilization across protocols</li>
+      <li>Reduced capital requirements through composability</li>
+    </ul>
+  </Card>
+
+  <Card title="Reliability" icon="shield-check" iconType="duotone">
+    <ul className="mt-2 space-y-1">
+      <li>Infrastructure failures are consensus failures</li>
+      <li>Guaranteed execution within block boundaries</li>
+    </ul>
+  </Card>
+
+  <Card title="Performance" icon="bolt" iconType="duotone">
+    <ul className="mt-2 space-y-1">
+      <li>Direct state access without contract calls</li>
+      <li>High-frequency oracle updates every block</li>
+    </ul>
+  </Card>
+
+  <Card title="Security" icon="lock" iconType="duotone">
+    <ul className="mt-2 space-y-1">
+      <li>Protocol-level validation of all operations</li>
+      <li>No trusted external oracles or bridges</li>
+    </ul>
+  </Card>
+</CardGroup>
+
+## Atomic Composability
+
+Neutron enables true atomic composability across all protocol features within a single transaction:
+
+```mermaid
+graph LR
+  A[Smart Contract] --> B[Oracle Module]
+  A --> C[Token Transfer]
+  A --> D[Interchain Query]
+  A --> E[Cron Automation]
+
+  B & C & D & E -.-> F[Unified Transaction State]
+
+  classDef default fill:#f5f5f5,stroke:#d9d9d9,color:#333
+  classDef contract fill:#0ea5e9,stroke:#0284c7,color:white
+
+  class A contract
+```
+
+All operations execute atomically in a single transaction context, providing developers with strong guarantees while eliminating interoperability risks.
+
+## Real-World Applications
+
+### Supervaults
+[Supervaults](/defi/supervaults) represent a new approach to liquidity provision that overcomes the limitations of traditional AMMs. By leveraging Neutron's built-in high-frequency oracle and native automation features, Supervaults can:
+
+- Market make at the most recent CEX prices
+- Automatically rebalance every block
+- Perform arbitrage themselves instead of being arbitraged
+- Democratize profits to liquidity providers
+
+### Cross-Chain Liquid Staking
+Protocols like [Drop](/defi/drop) can utilize Neutron's Interchain Accounts and Interchain Queries (ICQ) capabilities to:
+
+- Read the state of other blockchains
+- Adjust delegations made by remotely controlled accounts
+- Onboard new assets from connected chains with a single transaction
+- Provide users with a seamless cross-chain staking experience

concepts/modular-governance.mdx

@@ -0,0 +1,159 @@
+---
+title: "Modular Governance and Chain Management"
+description: "Neutron's governance system balances efficiency, security, and decentralization through a multi-layered architecture"
+icon: "scale-balanced"
+---
+
+Neutron's governance model uses a customized fork of DAO DAO contracts to create a flexible, multi-layered system where specialized committees handle day-to-day operations while remaining accountable to tokenholders through innovative oversight mechanisms.
+
+## Governance Architecture
+
+<CardGroup cols={2}>
+  <Card title="Neutron DAO (Agora)" icon="building-columns" iconType="duotone">
+    The primary governance entity with ultimate authority, governed by Neutron's stakeholders through the NTRN token. Controls network upgrades, crucial parameters, and committees.
+  </Card>
+
+  <Card title="Committees (subDAOs)" icon="sitemap" iconType="duotone">
+    Specialized governance entities with dedicated powers and resources for day-to-day operations like grants and incentive programs.
+  </Card>
+</CardGroup>
+
+**Chain Manager** mediates between governance and the blockchain's privileged functions through sophisticated permission strategies, enabling granular control of network operations.
+
+**Voting Vaults** are smart contracts that calculate governance power based on various tokenized positions containing NTRN.
+
+## How is Neutron Governance Different?
+
+<div className="p-4 border-l-4 border-primary bg-primary/5 rounded mb-6">
+  <strong>Key differences from traditional Cosmos governance:</strong>
+  <ul className="mt-2">
+    <li>Following the Mercury upgrade, Neutron is now a sovereign chain with its own validator set and staking model</li>
+    <li>Voting power comes from bonding NTRN or DeFi tokens containing NTRN through Voting Vaults</li>
+    <li>Native stakers can participate in governance through the Staked NTRN Voting Vault</li>
+    <li>Specialized Committees handle routine governance to minimize voter fatigue</li>
+    <li>Tokenholders can keep Committees accountable through "overrule proposals"</li>
+    <li>Chain Manager implements granular permission controls for privileged operations</li>
+  </ul>
+</div>
+
+## Chain Manager
+
+The Chain Manager implements a permission system to control which entities can execute privileged actions on the blockchain using two **permission strategies**: 
+
+- **ALLOW_ALL**: Grants an entity full access to all privileged functions without restriction
+- **ALLOW_ONLY**: Permits an entity to execute only specific message types with possible additional restrictions
+
+### Supported Privileged Messages
+
+<div className="overflow-x-auto">
+  <table className="w-full my-4 text-sm">
+    <thead>
+      <tr>
+        <th className="p-2 border-b-2 border-gray-200 bg-gray-100 dark:bg-gray-800 dark:border-gray-700">Message Type</th>
+        <th className="p-2 border-b-2 border-gray-200 bg-gray-100 dark:bg-gray-800 dark:border-gray-700">Description</th>
+        <th className="p-2 border-b-2 border-gray-200 bg-gray-100 dark:bg-gray-800 dark:border-gray-700">Possible Restrictions</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`params.ParamChangeProposal`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Changes parameters of modules using the deprecated params module</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Specific modules and parameters</td>
+      </tr>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`module_name.MsgUpdateParams`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Updates parameters of modules using the new-style param updates</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Specific fields within the message</td>
+      </tr>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`cron.AddSchedule`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Adds new execution schedules to the CRON module</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">None</td>
+      </tr>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`cron.RemoveSchedule`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Removes schedules from the CRON module</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">None</td>
+      </tr>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`upgrade.SoftwareUpgradeProposal`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Schedules a software upgrade</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">None</td>
+      </tr>
+      <tr>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700 font-mono text-xs">`upgrade.CancelSoftwareUpgradeProposal`</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">Cancels a scheduled upgrade</td>
+        <td className="p-2 border-b border-gray-200 dark:border-gray-700">None</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+### Permission Assignments
+
+Current permission assignments include: **Neutron DAO Core Contract** with ALLOW_ALL strategy for comprehensive network control, **Expedited Upgrades Multisig** with ALLOW_ONLY for software upgrade proposals and cancellations, and **Tokenfactory Hooks Multisig** with ALLOW_ONLY for updating tokenfactory hook parameters.
+
+## Neutron DAO (Agora)
+
+The Neutron DAO serves as the highest governance authority, with comprehensive control over the network, including permissions for committees.
+
+### Voting Power System
+
+Neutron uses dedicated smart contracts called **Voting Vaults** to calculate governance power. These vaults can accept any tokenized position containing NTRN:
+
+- **NTRN Vault**: Accepts NTRN deposits and grants 1 point of voting power per token without lock-up
+- **LP Token Vaults**: Accepts LP token deposits and counts the underlying NTRN (both NTRN-ATOM and NTRN-USDC pairs have Voting Vaults)
+- **Staked NTRN Vault**: Added during the Mercury upgrade, grants 1 point of governance power per NTRN delegated to validators via native staking
+- **Virtual Vaults**: Track NTRN held in other contracts (lockdrops, vesting contracts), ensuring all NTRN holders can participate in governance
+
+### Proposal Types
+
+<CardGroup cols={3}>
+  <Card title="Single-choice Proposals" icon="check" iconType="duotone">
+    Standard yes/no decisions with a 50% threshold
+  </Card>
+
+  <Card title="Multiple-choice Proposals" icon="list-check" iconType="duotone">
+    Decisions with multiple options where the most-voted option wins
+  </Card>
+
+  <Card title="Overrule Proposals" icon="ban" iconType="duotone">
+    Special proposals with a lower threshold (0.5%) for overruling subDAO decisions
+  </Card>
+</CardGroup>
+
+## Committees (subDAOs)
+
+The Agora can create specialized Committees with specific powers and resources for day-to-day operations. These subDAOs are customizable in terms of **membership** (defining who can participate), **voting weight** (configuring how votes are weighted), and **execution rights** (setting specific parameters and permissions).
+
+### Timelocks & Overrules
+
+<div className="p-4 border-l-4 border-primary bg-primary/5 rounded my-6">
+  <strong>The overrule mechanism works as follows:</strong>
+  <ol className="mt-2 space-y-2">
+    <li>When a subDAO proposal passes, it enters a timelock period (typically 3 days)</li>
+    <li>During this period, the main DAO can create an overrule proposal with a low threshold (0.5%)</li>
+    <li>If the overrule proposal passes, the subDAO proposal is rejected</li>
+    <li>If no overrule occurs, the subDAO proposal executes after the timelock period</li>
+  </ol>
+</div>
+
+### Security SubDAO
+
+A specialized subDAO that can only execute `pause()` methods on certain contracts, enabling rapid response to security incidents. This subDAO can pause other subDAOs, the Reserve contract, and the Distribution contract.
+
+## Benefits and Parameters
+
+**Efficiency**: Specialized committees handle routine matters, reducing governance overhead and minimizing voter fatigue.
+
+**Accountability**: Committees are given autonomy while the main DAO can overrule with low threshold, with timelock periods ensuring transparency.
+
+**Participation**: Voting Vaults enable DeFi participation, reducing opportunity costs with multiple ways to gain governance power.
+
+### Governance Parameters
+
+**Main DAO Proposals**: 1000 NTRN deposit (refunded for passed proposals), 2-week voting period, 5% quorum, 50% threshold for single-choice proposals.
+
+**Overrule Proposals**: No deposit required (created automatically), 3-day voting period, 0.5% threshold, revoting disabled for immediate execution.
+
+**Note**: Following the Mercury upgrade, Neutron operates as a sovereign chain with its own validator set and staking model, detailed in the [Proof of Liquid Staking](/concepts/proof-of-liquid-staking) documentation.