Improve reference documentation structure and add MCP config guidelines

.beads/config.yaml

@@ -42,7 +42,7 @@ issue-prefix: "flapi"
 # This setting persists across clones (unlike database config which is gitignored).
 # Can also use BEADS_SYNC_BRANCH env var for local override.
 # If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
-# sync-branch: "beads-sync"
+sync-branch: "beads-sync"
 
 # Multi-repo configuration (experimental - bd-307)
 # Allows hydrating from multiple repositories and routing writes to the correct JSONL
@@ -59,4 +59,4 @@ issue-prefix: "flapi"
 # - linear.url
 # - linear.api-key
 # - github.org
-# - github.repo
+# - github.repo

.beads/export-state/617757fd233dfc0b.json

@@ -0,0 +1,6 @@
+{
+  "worktree_root": "/tmp/flapi-mcp-dev",
+  "last_export_commit": "c024669ae57a4ca0fee32177dc043303d6646259",
+  "last_export_time": "2026-01-24T10:32:00.607589304+01:00",
+  "jsonl_hash": "0997d3480b4414eca6270d38aac3e4418efdf97b115fee27388905e30e8b5288"
+}

.beads/export-state/94d89d32f1b10114.json

@@ -0,0 +1,6 @@
+{
+  "worktree_root": "/home/jr/Projects/datazoo/flapi/.git/beads-worktrees/beads-sync",
+  "last_export_commit": "c024669ae57a4ca0fee32177dc043303d6646259",
+  "last_export_time": "2026-01-24T10:22:54.991560336+01:00",
+  "jsonl_hash": "2e4fb3b95e3d1af1ca4345707a3edf7a1f08ecb444d5ae9b9bb5e7072a69317f"
+}

.beads/export-state/c957ff376aa6cdc9.json

@@ -0,0 +1,6 @@
+{
+  "worktree_root": "/home/jr/Projects/datazoo/flapi",
+  "last_export_commit": "c024669ae57a4ca0fee32177dc043303d6646259",
+  "last_export_time": "2026-01-24T10:31:59.140175446+01:00",
+  "jsonl_hash": "0997d3480b4414eca6270d38aac3e4418efdf97b115fee27388905e30e8b5288"
+}

AGENTS.md

@@ -462,6 +462,49 @@ WHERE updated_at > TIMESTAMP '{{cache.previousSnapshotTimestamp}}'
 -- Only refresh rows changed since last snapshot
 ```
 
+## Commit Message Guidelines
+
+### Attribution Policy
+
+**Never include Claude Code attribution in commit messages.**
+
+Do NOT add lines like:
+```
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+```
+
+Rationale: Work is owned and authored by the human developer, even when AI assistance is used. AI is a tool, not a co-author.
+
+### Commit Message Format
+
+Commit messages should follow this format:
+
+```
+feat|fix|chore|docs|test: Brief description (imperative mood)
+
+- Bullet point explaining what changed
+- Why it changed (if not obvious)
+- Any relevant issue references (#123)
+```
+
+**Examples:**
+```
+feat: Add VFS support for cloud storage configuration
+- Enable S3, GCS, Azure paths in config files
+- Implement PathSchemeUtils for scheme detection
+- Add LocalFileProvider and DuckDBVFSProvider
+
+chore: Update documentation for reference structure
+- Consolidate authentication references
+- Add cross-reference sections to all docs
+- Create REFERENCE_MAP.md for navigation
+
+fix: Correct template expansion in DuckDB queries
+- Use triple braces for string parameters
+- Fix null handling in optional fields
+- Closes #42
+```
+
 ## Code Style and Conventions
 
 ### C++ (Backend)

CMakeLists.txt

@@ -238,6 +238,7 @@ add_library(flapi-lib STATIC
     src/mcp_error_builder.cpp
     src/mcp_request_validator.cpp
     src/mcp_client_capabilities.cpp
+    src/config_tool_adapter.cpp
     src/mcp_content_types.cpp
     src/mcp_auth_handler.cpp
     src/oidc_discovery_client.cpp

Readme.md

@@ -664,7 +664,15 @@ The build process will download and build DuckDB v1.1.2 and install the vcpkg pa
 
 ## 📚 Documentation
 
-For more detailed information, check out our [full documentation](link-to-your-docs).
+For more detailed information, check out our [full documentation](docs/):
+
+- **[Reference Documentation Map](docs/REFERENCE_MAP.md)** - Quick navigation guide for all docs
+- **[Configuration Reference](docs/CONFIG_REFERENCE.md)** - Complete flapi.yaml configuration options
+- **[MCP Reference](docs/MCP_REFERENCE.md)** - Model Context Protocol specification and implementation
+- **[Config Service API Reference](docs/CONFIG_SERVICE_API_REFERENCE.md)** - REST API for runtime configuration
+- **[CLI Reference](docs/CLI_REFERENCE.md)** - Server executable command-line options
+- **[Cloud Storage Guide](docs/CLOUD_STORAGE_GUIDE.md)** - Using cloud storage backends (S3, GCS, Azure)
+- **[Architecture & Design](docs/spec/)** - System architecture, design decisions, and component documentation
 
 ## 🤝 Contributing
 

docs/CLI_REFERENCE.md

@@ -239,7 +239,9 @@ Enables the runtime configuration management API.
 
 **Description:**
 
-When enabled, exposes REST API endpoints for managing endpoints, templates, and cache at runtime without server restart:
+When enabled, exposes REST API endpoints and MCP tools for managing endpoints, templates, and cache at runtime without server restart:
+
+**REST API Endpoints:**
 
 | Endpoint | Description |
 |----------|-------------|
@@ -254,7 +256,19 @@ When enabled, exposes REST API endpoints for managing endpoints, templates, and
 | `GET /api/v1/_schema` | Database schema introspection |
 | `POST /api/v1/_ping` | Health check |
 
-**Security:** All configuration service endpoints require authentication via bearer token.
+**MCP Tools (18 configuration management tools):**
+
+When config-service is enabled, 18 MCP configuration tools become available:
+- **Discovery Tools (5):** `flapi_get_project_config`, `flapi_get_environment`, `flapi_get_filesystem`, `flapi_get_schema`, `flapi_refresh_schema`
+- **Template Tools (4):** `flapi_get_template`, `flapi_update_template`, `flapi_expand_template`, `flapi_test_template`
+- **Endpoint Tools (6):** `flapi_list_endpoints`, `flapi_get_endpoint`, `flapi_create_endpoint`, `flapi_update_endpoint`, `flapi_delete_endpoint`, `flapi_reload_endpoint`
+- **Cache Tools (4):** `flapi_get_cache_status`, `flapi_refresh_cache`, `flapi_get_cache_audit`, `flapi_run_cache_gc`
+
+See [MCP Configuration Tools API Reference](./MCP_CONFIG_TOOLS_API.md) for complete tool documentation.
+
+**Important:** Without `--config-service`, these MCP tools will NOT be available. They do not appear in `tools/list` responses.
+
+**Security:** All configuration service endpoints and MCP tools require authentication via bearer token.
 
 **Example:**
 
@@ -440,6 +454,8 @@ echo $?  # 0 = valid, 1 = invalid
 
 ## Related Documentation
 
-- [Configuration Reference](./CONFIG_REFERENCE.md) - Comprehensive configuration file options
-- [Config Service API Reference](./CONFIG_SERVICE_API_REFERENCE.md) - Runtime configuration REST API
-- [MCP Reference](./MCP_REFERENCE.md) - Model Context Protocol implementation
+- **[Reference Documentation Map](./REFERENCE_MAP.md)** - Navigation guide for all reference docs
+- **[Configuration Reference](./CONFIG_REFERENCE.md)** - Configuration file options and format
+- **[Config Service API Reference](./CONFIG_SERVICE_API_REFERENCE.md)** - Runtime configuration REST API and CLI client
+- **[MCP Reference](./MCP_REFERENCE.md)** - Model Context Protocol specification
+- **[Cloud Storage Guide](./CLOUD_STORAGE_GUIDE.md)** - Using cloud storage backends with configuration files

docs/CLOUD_STORAGE_GUIDE.md

@@ -370,6 +370,7 @@ template-source: https://other-server.com/templates/customers.sql
 
 ## Related Documentation
 
-- [CONFIG_REFERENCE.md](./CONFIG_REFERENCE.md) - Full configuration reference
-- [CLI_REFERENCE.md](./CLI_REFERENCE.md) - Command-line options
-- [features/flapi-10-fs-abstraction.md](./features/flapi-10-fs-abstraction.md) - Technical design document
+- **[Reference Documentation Map](./REFERENCE_MAP.md)** - Navigation guide for all reference docs
+- **[Configuration Reference](./CONFIG_REFERENCE.md)** - Configuration file format (§ 2.11 for VFS configuration)
+- **[CLI Reference](./CLI_REFERENCE.md)** - Server command-line options including `--config`
+- **[Technical Design](./features/flapi-10-fs-abstraction.md)** - VFS abstraction implementation details

docs/CONFIG_REFERENCE.md

@@ -1704,6 +1704,10 @@ flAPI supports both hyphenated and camelCase naming for backward compatibility:
 
 ## Related Documentation
 
-- [CLI Reference](./CLI_REFERENCE.md) - Command-line interface documentation
-- [Config Service API Reference](./CONFIG_SERVICE_API_REFERENCE.md) - Runtime configuration REST API
-- [MCP Reference](./MCP_REFERENCE.md) - Model Context Protocol implementation details
+- **[Reference Documentation Map](./REFERENCE_MAP.md)** - Navigation guide for all reference docs
+- **[CLI Reference](./CLI_REFERENCE.md)** - Server executable command-line options
+- **[Config Service API Reference](./CONFIG_SERVICE_API_REFERENCE.md)** - Runtime configuration REST API and CLI client
+- **[MCP Reference](./MCP_REFERENCE.md)** - Model Context Protocol specification and implementation
+- **[MCP Configuration Tools API](./MCP_CONFIG_TOOLS_API.md)** - 20 MCP tools for configuration management
+- **[MCP Configuration Integration Guide](./MCP_CONFIG_INTEGRATION.md)** - Integration architecture and request/response flows
+- **[Cloud Storage Guide](./CLOUD_STORAGE_GUIDE.md)** - Using cloud storage backends (S3, GCS, Azure)

docs/CONFIG_SERVICE_API_REFERENCE.md

@@ -1532,6 +1532,8 @@ Slugs identify endpoints in API paths. The format depends on endpoint type:
 
 ## Related Documentation
 
-- [Configuration Reference](./CONFIG_REFERENCE.md) - Configuration file options
-- [CLI Reference](./CLI_REFERENCE.md) - Server executable options
-- [MCP Reference](./MCP_REFERENCE.md) - Model Context Protocol implementation
+- **[Reference Documentation Map](./REFERENCE_MAP.md)** - Navigation guide for all reference docs
+- **[Configuration Reference](./CONFIG_REFERENCE.md)** - Configuration file options and format
+- **[CLI Reference](./CLI_REFERENCE.md)** - Server executable command-line options
+- **[MCP Reference](./MCP_REFERENCE.md)** - Model Context Protocol specification
+- **[MCP Configuration Integration Guide](./MCP_CONFIG_INTEGRATION.md)** - How config tools integrate with MCP protocol