fix: repair dead links across documentation

docs/md/doc/builder-agent.md

@@ -4,7 +4,7 @@ The Builder Agent is focused on authoring and evolving semantic tables: defining
 
 ## Claude Code Skill
 
-- File: [`src/boring_semantic_layer/agents/claude-code/bsl-model-building/SKILL.md`](../../src/boring_semantic_layer/agents/claude-code/bsl-model-building/SKILL.md)
+- File: [`docs/md/skills/claude-code/bsl-model-builder/SKILL.md`](../skills/claude-code/bsl-model-builder/SKILL.md)
 - Use it when you want Claude Desktop to help write new semantic tables, add time dimensions, or compose models.
 - The skill includes:
   - Python DSL examples showing `SemanticTable(...)`, `.with_dimensions`, `.with_measures`, `.with_calculated_measures`, and `.join()` patterns.
@@ -17,7 +17,7 @@ The Builder Agent is focused on authoring and evolving semantic tables: defining
 
 Running inside the Codex CLI (the environment this assistant uses) already gives you repo access. Pair that with the Builder skill to automate scaffolding:
 
-1. Open `docs/content/semantic-table.md` or the relevant source file in your editor for context.
+1. Open `docs/md/doc/semantic-table.md` or the relevant source file in your editor for context.
 2. Ask Codex to "apply the builder skill" when drafting new semantic tables. It will reference `bsl-model-building/SKILL.md` to keep the API usage correct.
 3. Use the CLI's `apply_patch` output directly to drop in the generated models or YAML definitions.
 

docs/md/doc/getting-started.md

@@ -151,13 +151,13 @@ Then run:
 bsl chat --sm my_model.yaml
 ```
 
-See [Query Agent Chat](/examples/query-agent-chat) for full documentation on YAML models with joins and advanced features.
+See [Query Agent Chat](/agents/chat) for full documentation on YAML models with joins and advanced features.
 
 ## Next Steps
 
-- [Chat with your data](/examples/query-agent-chat) using natural language
-- Define models in [YAML configuration](/examples/yaml-config)
-- Configure database connections with [Profiles](/examples/profile)
-- Learn how to [Build Semantic Tables](/examples/semantic-table) with dimensions, measures, and joins
-- Explore [Query Methods](/examples/query-methods) for retrieving data
-- Discover how to [Compose Models](/examples/compose) together
+- [Chat with your data](/agents/chat) using natural language
+- Define models in [YAML configuration](/building/yaml)
+- Configure database connections with [Profiles](/building/profile)
+- Learn how to [Build Semantic Tables](/building/semantic-tables) with dimensions, measures, and joins
+- Explore [Query Methods](/querying/methods) for retrieving data
+- Discover how to [Compose Models](/building/compose) together

docs/md/doc/mcp.md

@@ -3,7 +3,7 @@
 BSL includes built-in support for the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk), allowing you to expose your semantic models to Large Language Models like Claude.
 
 <note type="info">
-**Pro tip:** Use [descriptions in dimensions and measures](/building/semantic-tables#adding-descriptions) to make your models more AI-friendly. Descriptions help provide context to LLMs, enabling them to understand what each field represents and when to use them.
+**Pro tip:** Use [descriptions in dimensions and measures](/building/semantic-tables#with_dimensions) to make your models more AI-friendly. Descriptions help provide context to LLMs, enabling them to understand what each field represents and when to use them.
 </note>
 
 ## Installation
@@ -20,8 +20,7 @@ Create an MCP server script that exposes your semantic models:
 
 ```python
 import ibis
-from boring_semantic_layer.semantic_api import to_semantic_table
-from boring_semantic_layer.api.mcp import MCPSemanticModel
+from boring_semantic_layer import to_semantic_table, MCPSemanticModel
 
 # Create synthetic flights data
 flights_data = ibis.memtable({
@@ -257,7 +256,7 @@ When exposing models through MCP, you need to explicitly define time dimensions
 To define a time dimension, set `is_time_dimension=True` and specify the `smallest_time_grain`:
 
 ```python
-from boring_semantic_layer.semantic_api import to_semantic_table
+from boring_semantic_layer import to_semantic_table
 
 flights = (
     to_semantic_table(flights_data, name="flights")

docs/md/doc/query-agent-mcp.md

@@ -3,7 +3,7 @@
 BSL includes built-in support for the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol/python-sdk), allowing you to expose your semantic models to Large Language Models like Claude.
 
 <note type="info">
-**Pro tip:** Use [descriptions in dimensions and measures](/building/semantic-tables#adding-descriptions) to make your models more AI-friendly. Descriptions help provide context to LLMs, enabling them to understand what each field represents and when to use them.
+**Pro tip:** Use [descriptions in dimensions and measures](/building/semantic-tables#with_dimensions) to make your models more AI-friendly. Descriptions help provide context to LLMs, enabling them to understand what each field represents and when to use them.
 </note>
 
 ## Installation

docs/md/doc/reference.md

@@ -89,7 +89,7 @@ Load semantic models from a YAML configuration file. Returns a dictionary of sem
 
 **Example:**
 ```python
-from boring_semantic_layer.yaml import from_yaml
+from boring_semantic_layer import from_yaml
 
 models = from_yaml("models.yaml")
 flights_st = models["flights"]

docs/md/doc/semantic-table.md

@@ -361,6 +361,6 @@ date_range_join = flights_st.join(
 
 ## Next Steps
 
-- Learn about [Composing Models](/examples/compose)
-- Explore [YAML Configuration](/examples/yaml-config)
-- Start [Querying Semantic Tables](/examples/query-methods)
+- Learn about [Composing Models](/building/compose)
+- Explore [YAML Configuration](/building/yaml)
+- Start [Querying Semantic Tables](/querying/methods)