SylphAI-Inc · Tanglumy · Nov 27, 2025 · Nov 27, 2025 · Dec 24, 2025 · Dec 24, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,194 @@
+# AGENTS.md
+
+This file provides guidance to agents (i.e., ADAL) when working with code in this repository.
+
+## Repository Overview
+
+This is the **public documentation site** for AdaL CLI, built with Docusaurus. It's a standalone documentation repo separate from the main AdaL codebase.
+
+**Main codebase**: See `../adal/AGENTS.md` for guidance on working with the core AdaL CLI, backend, and tools.
+
+## Project Structure
+
+```
+adal-cli-public/
+├── docs-site/          # Docusaurus site
+│   ├── docs/           # Documentation content (markdown)
+│   ├── blog/           # Blog posts
+│   ├── src/            # React components and custom pages
+│   ├── static/         # Static assets (images, etc.)
+│   └── build/          # Generated static site (gitignored)
+├── INPUT_GUIDE.md      # User guide for input methods (created during docs work)
+└── README.md           # Repository overview
+```
+
+## Essential Commands
+
+All commands run from `docs-site/` directory:
+
+```bash
+cd docs-site
+
+# Install dependencies (first time or after package.json changes)
+npm install
+
+# Start development server with hot reload
+npm run start
+# Opens at http://localhost:3000
+
+# Build static site for production
+npm run build
+# Output in docs-site/build/
+
+# Serve built site locally (must build first)
+npm run serve
+
+# Clear Docusaurus cache
+npm run clear
+
+# Type checking
+npm run typecheck
+```
+
+### Critical Gotchas
+
+- **Node version**: Requires Node >=18.0 (check with `node --version`)
+- **Working directory**: Commands must run from `docs-site/` directory, not repo root
+- **No tests**: This is a pure documentation site - no test suite
+- **Build before serve**: `npm run serve` requires running `npm run build` first
+
+## Documentation Structure
+
+### Content Organization
+
+Documentation lives in `docs-site/docs/` with this structure:
+
+- `01-getting-started/` - Installation, setup, first steps
+- `03-features/` - Feature documentation
+- `07-troubleshooting/` - Common issues and solutions
+- `build-with-adal/` - Advanced usage and examples
+
+### Adding/Editing Documentation
+
+1. **Create new doc**: Add `.md` or `.mdx` file in appropriate subdirectory
+2. **Front matter**: Each doc needs front matter:
+   ```markdown
+   ---
+   title: Page Title
+   sidebar_position: 1
+   ---
+   ```
+3. **Sidebar config**: Edit `docs-site/sidebars.ts` if you need custom sidebar ordering
+4. **Preview changes**: Use `npm run start` to see changes live at http://localhost:3000
+
+### Markdown Features
+
+Docusaurus supports:
+- Standard markdown
+- MDX (React components in markdown)
+- Admonitions (:::note, :::tip, :::warning, :::danger)
+- Code blocks with syntax highlighting
+- Tabs and other interactive elements
+
+## Configuration Files
+
+- `docs-site/docusaurus.config.ts` - Main Docusaurus configuration (site metadata, navbar, footer, theme)
+- `docs-site/sidebars.ts` - Documentation sidebar structure
+- `docs-site/package.json` - Dependencies and npm scripts
+- `docs-site/tsconfig.json` - TypeScript configuration
+
+## Key Entry Points
+
+- **Docusaurus config**: `docs-site/docusaurus.config.ts` - controls site title, navbar, footer, plugins
+- **Homepage**: `docs-site/src/pages/index.tsx` - custom React landing page
+- **Custom styles**: `docs-site/src/css/custom.css` - global CSS variables and overrides
+- **Static assets**: `docs-site/static/` - images, logos, favicon
+
+## Docusaurus-Specific Patterns
+
+### Internal Links
+
+Use relative paths without `.md` extension:
+```markdown
+[Getting Started](../getting-started/installation)
+```
+
+### Images
+
+Place in `docs-site/static/img/` and reference from markdown:
+```markdown
+![Alt text](/img/screenshot.png)
+```
+
+### Admonitions
+
+```markdown
+:::note
+This is a note
+:::
+
+:::tip
+Helpful tip here
+:::
+
+:::warning
+Be careful!
+:::
+```
+
+## Common Tasks
+
+### Preview Documentation Locally
+
+```bash
+cd docs-site
+npm install  # if first time
+npm run start
+```
+
+Site opens at http://localhost:3000 with hot reload.
+
+### Add New Documentation Page
+
+1. Create `.md` file in appropriate `docs-site/docs/` subdirectory
+2. Add front matter with title and sidebar position
+3. Write content using Markdown/MDX
+4. Check preview with `npm run start`
+
+### Update Navigation
+
+- **Navbar**: Edit `docusaurus.config.ts` → `themeConfig.navbar`
+- **Sidebar**: Edit `sidebars.ts` or use `sidebar_position` in front matter
+
+### Build for Production
+
+```bash
+cd docs-site
+npm run build
+npm run serve  # Test built site locally
+```
+
+## Relationship to Main Codebase
+
+This documentation site describes the **AdaL CLI** tool (the main product), but lives in a **separate repository** from the AdaL CLI source code.
+
+- **This repo** (`adal-cli-public`): Public documentation only
+- **Main repo** (`../adal/`): AdaL CLI source, backend, tools, private docs
+
+When documenting:
+- Focus on **user-facing features** and **how-to guides**
+- Avoid implementation details (those belong in main repo's private docs)
+- Keep examples practical and tested
+
+## Workflow Notes
+
+- **No tests**: Documentation-only repo, no testing infrastructure
+- **No linting**: Standard Docusaurus setup, no custom linters configured
+- **Git branch**: Currently on `new-branch` - merge to main when ready
+
+## Reference Parent Repo
+
+For context about the actual AdaL CLI implementation:
+- Main AGENTS.md: `../adal/AGENTS.md`
+- Feature specs: `../adal/docs/adal/fea_*.md`
+- Source code: `../adal/adal-cli/`, `../adal/deep_research/`, `../adal/tools/`
diff --git a/README.md b/README.md
@@ -1,33 +1,111 @@
-# ADAL CLI Documentation
+# AdaL CLI Documentation
 
-This repository contains the public documentation site for ADAL CLI, built with Docusaurus.
+<div align="center">
+  <img src="docs-site/static/adal-face-logo.svg" alt="AdaL Face" width="150" />
+  &nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="docs-site/static/adal-text-logo.svg" alt="AdaL Text" width="280" />
+  <br /><br />
+  <strong>Your self-evolving agent for engineering and research</strong>
+  <br /><br />
 
-## Overview
+  [![Docs](https://img.shields.io/badge/docs-docs.sylph.ai-blue)](https://docs.sylph.ai)
+  [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/ezzszrRZvT)
+  [![X](https://img.shields.io/badge/follow-%40adalengineer-black?logo=x)](https://x.com/adalengineer)
 
-AdaL CLI is your AI companion for engineering and research.
+  <br />
 
-## Documentation Site
+  <a href="https://www.youtube.com/watch?v=3kLl0V4uDR8">
+    <img src="https://img.youtube.com/vi/3kLl0V4uDR8/maxresdefault.jpg" alt="AdaL CLI Demo" width="600" />
+  </a>
+  <br />
+  <a href="https://www.youtube.com/watch?v=3kLl0V4uDR8">▶️ Watch the demo on YouTube</a>
+</div>
 
-This site provides comprehensive documentation including:
+---
 
-- Quickstart guide
-- API Reference
-- Tutorials and Examples
-- Advanced Topics
-- Community Resources
+## About
 
-## Development
+This is the **public documentation site** for [AdaL CLI](https://docs.sylph.ai/). AdaL is an agentic coding tool that runs in your terminal, created by [SylphAI](https://sylph.ai/) and named after Ada Lovelace, the world's first programmer.
+
+**What you can do here:**
+
+- Report issues with AdaL CLI agent behavior
+- Suggest documentation fixes or improvements
+- Contribute to make the docs better
+
+### Install AdaL CLI
 
 ```bash
-cd docs-site
+npm install -g @sylphai/adal-cli
+
+# cd to your working directory and run
+adal
+```
+
+Requires [Node.js 20+](https://nodejs.org/en/download). See [Quickstart](https://docs.sylph.ai/getting-started/quickstart) for details.
+
+## 🐛 Reporting Issues
+
+Found a bug or something wrong in the docs?
+
+**[Open an Issue →](https://github.com/SylphAI-Inc/adal-cli/issues/new)**
+
+Please include:
+- What you expected vs what happened
+- Steps to reproduce (if applicable)
+- AdaL CLI version (`adal -v`)
+- OS and terminal
+
+## 📝 Contributing
+
+We welcome documentation improvements!
 
-# Install dependencies
+### Quick Edits
+
+1. Find the page you want to fix at [docs.sylph.ai](https://docs.sylph.ai)
+2. Locate the corresponding file in `docs-site/docs/`
+3. Edit and submit a PR
+
+### Running Locally
+
+```bash
+cd docs-site
 npm install
+npm run start    # Dev server at http://localhost:3000
+npm run build    # Production build
+```
 
-# Start development server
-npm run start
+### Guidelines
 
-# Build for production
-npm run build
+- Keep docs clear and concise
+- Test changes locally with `npm run build`
+- Follow existing formatting conventions
+
+## Project Structure
+
+```
+docs-site/
+├── docs/                    # Documentation pages (markdown)
+│   ├── 01-getting-started/  # Quickstart, models, workflows
+│   ├── 03-features/         # Feature docs (shortcuts, commands, skills)
+│   ├── 07-troubleshooting/  # Common issues and solutions
+│   └── build-with-adal/     # Advanced usage
+├── static/                  # Images and assets
+└── src/                     # Custom CSS and components
 ```
 
+## Links
+
+- **Docs:** [docs.sylph.ai](https://docs.sylph.ai)
+- **GitHub:** [github.com/SylphAI-Inc/adal-cli](https://github.com/SylphAI-Inc/adal-cli)
+- **X (Twitter):** [@adalengineer](https://x.com/adalengineer)
+- **Discord:** [Join our community](https://discord.com/invite/ezzszrRZvT)
+- **SylphAI:** [sylph.ai](https://sylph.ai)
+
+---
+
+<div align="center">
+  <!-- <strong>Star <a href="https://github.com/SylphAI-Inc/adal-cli">AdaL CLI</a> · Follow <a href="https://x.com/adalengineer">@adalengineer</a></strong>
+  <br /> -->
+  Built with <a href="https://docusaurus.io/">Docusaurus</a> by AdaL & <a href="https://sylph.ai">SylphAI</a>
+</div>
diff --git a/docs-site/.node-version b/docs-site/.node-version
@@ -0,0 +1 @@
+20
diff --git a/docs-site/.nvmrc b/docs-site/.nvmrc
@@ -0,0 +1 @@
+20
diff --git a/docs-site/TODO.md b/docs-site/TODO.md
@@ -0,0 +1,6 @@
+# Documentation TODO
+
+## Planned Features
+
+- [ ] **i18n Support** - Add internationalization for multi-language documentation
+- [ ] **Search** - Add full-text search functionality
diff --git a/docs-site/docs/03-features/mcp-support.md → docs-site/archive/mcp-support.md b/docs-site/docs/03-features/mcp-support.md → docs-site/archive/mcp-support.md
@@ -1,8 +1,13 @@
 ---
-sidebar_position: 3
-title: MCP Support
+unlisted: true
+title: MCP Support (Archive)
 ---
 
+:::warning Not Used
+This file is archived and hidden from the sidebar. Saved for reference only.
+The current MCP documentation is in `mcp-support-proposed.md` → "MCP".
+:::
+
 
 # MCP Quick Reference Guide
 
@@ -108,7 +113,8 @@ Done! Now AdaL can use the server's tools.
 **API Key Services** (set environment variable first):
 ```bash
 # Set your token
-export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
+export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"  # macOS / Linux
+$env:GITHUB_TOKEN="ghp_xxxxxxxxxxxx"    # Windows PowerShell
 
 # Add server
 /mcp add github      # Repositories and issues
@@ -206,10 +212,12 @@ Examples:
 # Slack: https://api.slack.com/apps
 
 # 2. Set your token (AdaL must be closed)
-export GITHUB_TOKEN="your_token_here"
+export GITHUB_TOKEN="your_token_here"       # macOS / Linux
+$env:GITHUB_TOKEN="your_token_here"         # Windows PowerShell
 
 # 3. Verify the token is set (should display your token)
-echo $GITHUB_TOKEN
+echo $GITHUB_TOKEN                          # macOS / Linux
+echo $env:GITHUB_TOKEN                      # Windows PowerShell
 
 # 4. Add server
 /mcp add github
@@ -223,12 +231,21 @@ adal
 **How to verify**: After adding the server, AdaL will display "X tools available" (e.g., "26 tools available" for GitHub). This confirms your token is valid and the server is working.
 
 **Make it permanent** (survives terminal restarts):
+
+*macOS / Linux:*
 ```bash
 # Add to shell config (run once)
 echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.zshrc
 source ~/.zshrc
 ```
 
+*Windows PowerShell:*
+```powershell
+# Set as user environment variable (permanent)
+[System.Environment]::SetEnvironmentVariable('GITHUB_TOKEN', 'your_token_here', 'User')
+# Restart terminal to apply
+```
+
 **Token storage**: API keys are stored in your **environment**, not by AdaL. AdaL reads them from env vars each time it starts.
 
 ---