formatting

docs/skills/copilot-customization/references/vscode-customization.md

@@ -4,13 +4,14 @@ Use these notes as a source map before creating or debugging Copilot customizati
 
 ## Official Sources
 
-- Customization overview: https://code.visualstudio.com/docs/copilot/customization/overview
+!!! info "Official sources"
-- Custom instructions: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
+    - [Customization overview](https://code.visualstudio.com/docs/copilot/customization/overview)
-- Agent skills: https://code.visualstudio.com/docs/copilot/customization/agent-skills
+    - [Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
-- Prompt files: https://code.visualstudio.com/docs/copilot/customization/prompt-files
+    - [Agent skills](https://code.visualstudio.com/docs/copilot/customization/agent-skills)
-- Custom agents: https://code.visualstudio.com/docs/copilot/customization/custom-agents
+    - [Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)
-- MCP servers: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
+    - [Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
-- Hooks: https://code.visualstudio.com/docs/copilot/customization/hooks
+    - [MCP servers](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+    - [Hooks](https://code.visualstudio.com/docs/copilot/customization/hooks)
 
 ## Customization Types
 

docs/skills/fastapi-async-sqlalchemy-modernization/SKILL.md

@@ -33,37 +33,37 @@ Use these concepts as the planning backbone:
 
 1. Engine lifecycle and ownership:
    One AsyncEngine per process for each DB URL, created once and disposed explicitly when the app lifecycle ends.
-   See: [references/engine.md](references/engine.md)
+   See the [engine lifecycle reference](references/engine.md).
 2. Session factory and scope:
    Use async_sessionmaker for configuration; create one AsyncSession per request or unit-of-work, never shared across concurrent tasks.
-   See: [references/session.md](references/session.md)
+   See the [session management reference](references/session.md).
 3. Transaction boundaries:
    Prefer context-managed begin blocks for write units and explicit read-only sessions for queries.
-   See: [references/transactions.md](references/transactions.md)
+   See the [transaction boundaries reference](references/transactions.md).
 4. Lifespan composition:
    Compose startup/shutdown resources with AsyncExitStack so cleanup is deterministic and ordered.
-   See: [references/engine.md](references/engine.md)
+   See the [engine lifecycle reference](references/engine.md).
 5. Dependency injection:
    Provide sessions via FastAPI dependencies with async generators/context managers, not globals.
-   See: [references/session.md](references/session.md)
+   See the [session management reference](references/session.md).
 6. Implicit I/O control in ORM:
    Avoid accidental lazy loads; use explicit eager-loading/refresh strategies for asyncio safety.
-   See: [references/implicit_io.md](references/implicit_io.md)
+   See the [implicit I/O reference](references/implicit_io.md).
 7. Observability and resilience:
    Add pool/connection settings, logging, timeout, and health checks as first-class plan items.
-   See: [references/observability.md](references/observability.md)
+   See the [observability reference](references/observability.md).
 
 ### Concept Reference Map
 
 | Concept | Reference |
 |---|---|
-| Engine lifecycle and ownership | [references/engine.md](references/engine.md) |
+| Engine lifecycle and ownership | [Engine lifecycle reference](references/engine.md) |
-| Session factory and scope | [references/session.md](references/session.md) |
+| Session factory and scope | [Session management reference](references/session.md) |
-| Transaction boundaries | [references/transactions.md](references/transactions.md) |
+| Transaction boundaries | [Transaction boundaries reference](references/transactions.md) |
-| Lifespan composition | [references/engine.md](references/engine.md) |
+| Lifespan composition | [Engine lifecycle reference](references/engine.md) |
-| Dependency injection | [references/session.md](references/session.md) |
+| Dependency injection | [Session management reference](references/session.md) |
-| Implicit I/O control in ORM | [references/implicit_io.md](references/implicit_io.md) |
+| Implicit I/O control in ORM | [Implicit I/O reference](references/implicit_io.md) |
-| Observability and resilience | [references/observability.md](references/observability.md) |
+| Observability and resilience | [Observability reference](references/observability.md) |
 
 ## Decision Points
 
@@ -235,6 +235,7 @@ Return the plan as:
 
 ## References
 
-- SQLAlchemy engine/connections: https://docs.sqlalchemy.org/en/21/core/connections.html
+!!! info "Primary sources"
-- SQLAlchemy asyncio extension: https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html
+   - [SQLAlchemy engine and connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
-- Python async context managers and AsyncExitStack: https://docs.python.org/3/library/contextlib.html
+   - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
+   - [Python async context managers and AsyncExitStack](https://docs.python.org/3/library/contextlib.html)

docs/skills/fastapi-async-sqlalchemy-modernization/references/engine.md

@@ -1,10 +1,10 @@
 # Async SQLAlchemy Engine
 
-Source:
+!!! info "Primary sources"
-- https://docs.sqlalchemy.org/en/21/core/connections.html
+    - [SQLAlchemy connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
-- https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-- https://docs.sqlalchemy.org/en/21/core/pooling.html#pooling-multiprocessing
+    - [SQLAlchemy pooling and multiprocessing](https://docs.sqlalchemy.org/en/21/core/pooling.html#pooling-multiprocessing)
-- https://fastapi.tiangolo.com/advanced/events/
+    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
 
 ---
 
@@ -16,7 +16,7 @@ Create one async engine per process per database URL and keep it for the app lif
 - In FastAPI, app startup and shutdown ownership belongs in lifespan.
 - Use `FastAPI(lifespan=...)` (not startup/shutdown events) for modern lifecycle wiring.
 
-Practical rule:
+!!! tip "Practical rule"
     - Exactly one `create_async_engine(...)` call in app bootstrap code.
     - Zero `create_async_engine(...)` calls in request handlers.
 
@@ -69,8 +69,8 @@ Use SQLAlchemy async driver URLs:
 - PostgreSQL: `postgresql+asyncpg://user:pass@host:5432/dbname`
 - SQLite: `sqlite+aiosqlite:///./app.db`
 
-Notes:
+!!! warning "Driver compatibility"
-- Do not mix sync drivers (for example `psycopg2`) with `create_async_engine()`.
+    - Do not mix sync drivers, for example `psycopg2`, with `create_async_engine()`.
     - Keep URL construction centralized in settings/config, not in feature modules.
 
 ---

docs/skills/fastapi-async-sqlalchemy-modernization/references/implicit_io.md

@@ -1,13 +1,14 @@
 # Preventing Implicit ORM I/O (Asyncio)
 
-Source:
+!!! info "Primary sources"
-- https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html#preventing-implicit-io-when-using-asyncsession
+    - [Preventing implicit I/O with AsyncSession](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html#preventing-implicit-io-when-using-asyncsession)
-- https://docs.sqlalchemy.org/en/21/orm/queryguide/relationships.html
+    - [SQLAlchemy relationship loading](https://docs.sqlalchemy.org/en/21/orm/queryguide/relationships.html)
 
-Status: adopted
+??? abstract "Decision metadata"
-Decision level: advisory
+    - Status: adopted
-Applies to: api-runtime, workers, tests
+    - Decision level: advisory
-Last reviewed: 2026-06-17
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-06-17
 
 ---
 

docs/skills/fastapi-async-sqlalchemy-modernization/references/observability.md

@@ -1,15 +1,16 @@
 # DB Observability and Resilience
 
-Source:
+!!! info "Primary sources"
-- https://docs.sqlalchemy.org/en/21/core/pooling.html
+    - [SQLAlchemy pooling](https://docs.sqlalchemy.org/en/21/core/pooling.html)
-- https://docs.sqlalchemy.org/en/21/core/engines.html
+    - [SQLAlchemy engine configuration](https://docs.sqlalchemy.org/en/21/core/engines.html)
-- https://docs.sqlalchemy.org/en/21/core/events.html
+    - [SQLAlchemy events](https://docs.sqlalchemy.org/en/21/core/events.html)
-- https://fastapi.tiangolo.com/advanced/events/
+    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
 
-Status: adopted
+??? abstract "Decision metadata"
-Decision level: mandatory
+    - Status: adopted
-Applies to: api-runtime, workers, tests
+    - Decision level: mandatory
-Last reviewed: 2026-06-17
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-06-17
 
 ---
 

docs/skills/fastapi-async-sqlalchemy-modernization/references/session.md

@@ -1,14 +1,15 @@
 # Async SQLAlchemy Session Management
 
-Source:
+!!! info "Primary sources"
-- https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-- https://docs.sqlalchemy.org/en/21/orm/session_basics.html
+    - [SQLAlchemy session basics](https://docs.sqlalchemy.org/en/21/orm/session_basics.html)
-- https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/
+    - [FastAPI dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
 
-Status: adopted
+??? abstract "Decision metadata"
-Decision level: mandatory
+    - Status: adopted
-Applies to: api-runtime, workers, tests
+    - Decision level: mandatory
-Last reviewed: 2026-06-17
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-06-17
 
 ---
 

docs/skills/fastapi-async-sqlalchemy-modernization/references/template.md

@@ -1,13 +1,14 @@
 # <Concept Title>
 
-Source:
+!!! info "Primary sources"
-- <primary source url>
+    - Primary source: `<primary source URL>`
-- <secondary source url>
+    - Secondary source: `<secondary source URL>`
 
-Status: draft|adopted|deprecated
+??? abstract "Decision metadata"
-Decision level: advisory|mandatory
+    - Status: draft|adopted|deprecated
-Applies to: api-runtime|workers|tests
+    - Decision level: advisory|mandatory
-Last reviewed: YYYY-MM-DD
+    - Applies to: api-runtime|workers|tests
+    - Last reviewed: YYYY-MM-DD
 
 ---
 

docs/skills/fastapi-async-sqlalchemy-modernization/references/transactions.md

@@ -1,14 +1,15 @@
 # Async Transaction Boundaries
 
-Source:
+!!! info "Primary sources"
-- https://docs.sqlalchemy.org/en/21/orm/session_transaction.html
+    - [SQLAlchemy transactions](https://docs.sqlalchemy.org/en/21/orm/session_transaction.html)
-- https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html
+    - [SQLAlchemy asyncio extension](https://docs.sqlalchemy.org/en/21/orm/extensions/asyncio.html)
-- https://docs.sqlalchemy.org/en/21/core/connections.html
+    - [SQLAlchemy connections](https://docs.sqlalchemy.org/en/21/core/connections.html)
 
-Status: adopted
+??? abstract "Decision metadata"
-Decision level: mandatory
+    - Status: adopted
-Applies to: api-runtime, workers, tests
+    - Decision level: mandatory
-Last reviewed: 2026-06-17
+    - Applies to: api-runtime, workers, tests
+    - Last reviewed: 2026-06-17
 
 ---
 

docs/skills/fastapi-uv-docker/SKILL.md

@@ -22,10 +22,10 @@ Bring an existing Python project into full conformance with cloud-native best pr
 
 Load these references only when needed:
 
-- FastAPI patterns and app structure: [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md)
+- FastAPI patterns and app structure: [FastAPI best practices](./references/fastapi-best-practices.md)
-- uv project layout and dependency management: [./references/uv-project-layout.md](./references/uv-project-layout.md)
+- uv project layout and dependency management: [uv project layout](./references/uv-project-layout.md)
-- uvicorn CLI settings reference: [./references/uvicorn-settings.md](./references/uvicorn-settings.md)
+- uvicorn CLI settings reference: [uvicorn settings](./references/uvicorn-settings.md)
-- Docker and cloud-native patterns: [./references/docker-cloud-native.md](./references/docker-cloud-native.md)
+- Docker and cloud-native patterns: [Docker cloud-native patterns](./references/docker-cloud-native.md)
 
 ---
 
@@ -44,9 +44,9 @@ Before making changes, map the current state across six areas. Produce a short g
 | **Container** | Is there a `Dockerfile`? Multi-stage? Non-root user? `.dockerignore` present? |
 | **Cloud-native** | Is there a `/healthz` endpoint? Graceful shutdown? Structured logs? |
 
-Load [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md) for structure rules.
+Load the [FastAPI best practices reference](./references/fastapi-best-practices.md) for structure rules.
-Load [./references/uv-project-layout.md](./references/uv-project-layout.md) for uv migration rules.
+Load the [uv project layout reference](./references/uv-project-layout.md) for uv migration rules.
-Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for uvicorn CLI reference.
+Load the [uvicorn settings reference](./references/uvicorn-settings.md) for uvicorn CLI reference.
 
 Completion check: You can name every gap before touching any file.
 
@@ -145,7 +145,7 @@ Completion check: `uv run python -m my_app` starts the server.
 
 ### Step 3: Wire the FastAPI App Factory
 
-Load [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md) for the full patterns. Key rules:
+Load the [FastAPI best practices reference](./references/fastapi-best-practices.md) for the full patterns. Key rules:
 
 **`src/my_app/main.py`:**
 
@@ -211,7 +211,7 @@ Completion check: `uv run uvicorn my_app.main:app --reload` starts with no impor
 
 ### Step 4: uvicorn Production Configuration
 
-Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for the full settings reference.
+Load the [uvicorn settings reference](./references/uvicorn-settings.md) for the full settings reference.
 
 **Never** configure uvicorn inside application code. Pass all settings via CLI or environment variables (`UVICORN_*` prefix).
 
@@ -270,7 +270,7 @@ Completion check: `curl http://localhost:8000/healthz` returns `{"status":"ok"}`
 
 ### Step 5: Write the Dockerfile
 
-Load [./references/docker-cloud-native.md](./references/docker-cloud-native.md) for the full template and cloud-native rules. Key requirements:
+Load the [Docker cloud-native patterns reference](./references/docker-cloud-native.md) for the full template and cloud-native rules. Key requirements:
 
 - Multi-stage build: `builder` stage installs deps; `runtime` stage is slim.
 - Pin uv version (copy from official image, not `latest`).

docs/skills/fastapi-uv-docker/references/docker-cloud-native.md

@@ -1,6 +1,10 @@
 # Docker and Cloud-Native Patterns
 
-Source: https://docs.docker.com/build/building/best-practices/ | https://docs.astral.sh/uv/guides/integration/docker/ | https://fastapi.tiangolo.com/deployment/docker/ | https://uvicorn.dev/deployment/
+!!! info "Primary sources"
+    - [Docker build best practices](https://docs.docker.com/build/building/best-practices/)
+    - [uv Docker integration](https://docs.astral.sh/uv/guides/integration/docker/)
+    - [FastAPI Docker deployment](https://fastapi.tiangolo.com/deployment/docker/)
+    - [uvicorn deployment](https://uvicorn.dev/deployment/)
 
 ---
 

docs/skills/fastapi-uv-docker/references/fastapi-best-practices.md

@@ -1,6 +1,8 @@
 # FastAPI Best Practices
 
-Source: https://fastapi.tiangolo.com/deployment/ | https://fastapi.tiangolo.com/advanced/events/
+!!! info "Primary sources"
+    - [FastAPI deployment](https://fastapi.tiangolo.com/deployment/)
+    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)
 
 ---
 
@@ -44,7 +46,8 @@ def create_app(settings: Settings | None = None) -> FastAPI:
 app = create_app()
 ```
 
-**Never use `@app.on_event("startup")` / `@app.on_event("shutdown")`** — these are deprecated. The `asynccontextmanager` lifespan is the canonical approach since FastAPI 0.95.
+!!! warning "Prefer lifespan handlers"
+    Never use `@app.on_event("startup")` / `@app.on_event("shutdown")`. These are deprecated. The `asynccontextmanager` lifespan is the canonical approach since FastAPI 0.95.
 
 ---
 

docs/skills/fastapi-uv-docker/references/uv-project-layout.md

@@ -1,6 +1,9 @@
 # uv Project Layout and Dependency Management
 
-Source: https://docs.astral.sh/uv/guides/projects/ | https://docs.astral.sh/uv/concepts/projects/layout/ | https://docs.astral.sh/uv/guides/integration/docker/
+!!! info "Primary sources"
+    - [uv project guide](https://docs.astral.sh/uv/guides/projects/)
+    - [uv project layout](https://docs.astral.sh/uv/concepts/projects/layout/)
+    - [uv Docker integration](https://docs.astral.sh/uv/guides/integration/docker/)
 
 ---
 
@@ -13,7 +16,8 @@ Source: https://docs.astral.sh/uv/guides/projects/ | https://docs.astral.sh/uv/c
 | `.python-version` | Default Python version for the project | Yes |
 | `.venv/` | Local virtual environment | No (`.gitignore`) |
 
-**`uv.lock` must be committed.** It is the source of truth for reproducible installs in CI and Docker. Never edit it by hand.
+!!! warning "Commit the lockfile"
+    `uv.lock` must be committed. It is the source of truth for reproducible installs in CI and Docker. Never edit it by hand.
 
 ---
 

docs/skills/fastapi-uv-docker/references/uvicorn-settings.md

@@ -1,6 +1,8 @@
 # uvicorn Settings Reference
 
-Source: https://uvicorn.dev/settings/ | https://uvicorn.dev/deployment/
+!!! info "Primary sources"
+    - [uvicorn settings](https://uvicorn.dev/settings/)
+    - [uvicorn deployment](https://uvicorn.dev/deployment/)
 
 ---
 
@@ -21,7 +23,8 @@ uvicorn main:app
 uvicorn.run("main:app", host="0.0.0.0", port=8000)
 ```
 
-**Note:** `UVICORN_*` env vars cannot be used from within an `--env-file`. The `--env-file` flag is for the ASGI *application's* config, not uvicorn's own config.
+!!! note "Environment file scope"
+    `UVICORN_*` env vars cannot be used from within an `--env-file`. The `--env-file` flag is for the ASGI *application's* config, not uvicorn's own config.
 
 ---
 

docs/skills/nicegui-ui-customization/SKILL.md

@@ -29,9 +29,9 @@ Deliver a responsive, accessible UI flow that:
 
 Load these references only when needed:
 
-- Architecture and styling rules: [./references/architecture-and-styling.md](./references/architecture-and-styling.md)
+- Architecture and styling rules: [architecture and styling](./references/architecture-and-styling.md)
-- Event and state interaction patterns: [./references/interaction-patterns.md](./references/interaction-patterns.md)
+- Event and state interaction patterns: [interaction patterns](./references/interaction-patterns.md)
-- Troubleshooting and release gates: [./references/troubleshooting-and-quality-gates.md](./references/troubleshooting-and-quality-gates.md)
+- Troubleshooting and release gates: [troubleshooting and quality gates](./references/troubleshooting-and-quality-gates.md)
 
 ## Procedure
 

docs/skills/nicegui-ui-customization/references/architecture-and-styling.md

@@ -70,7 +70,8 @@ ui.add_css(open("src/app/static/css/base.css").read())
 
 ## Links
 
-- NiceGUI elements: https://nicegui.io/documentation/element
+!!! info "Primary sources"
-- NiceGUI binding: https://nicegui.io/documentation/section_binding_properties
+    - [NiceGUI elements](https://nicegui.io/documentation/element)
-- Tailwind: https://tailwindcss.com/docs/utility-first
+    - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
-- Quasar components: https://quasar.dev/vue-components
+    - [Tailwind utility-first styling](https://tailwindcss.com/docs/utility-first)
+    - [Quasar components](https://quasar.dev/vue-components)

docs/skills/nicegui-ui-customization/references/interaction-patterns.md

@@ -104,6 +104,7 @@ ui.button("Refresh").on_click(lambda: item_list.refresh())
 
 ## Links
 
-- NiceGUI action events: https://nicegui.io/documentation/section_action_events
+!!! info "Primary sources"
-- FastAPI SSE: https://fastapi.tiangolo.com/advanced/server-sent-events/
+    - [NiceGUI action events](https://nicegui.io/documentation/section_action_events)
-- FastAPI WebSockets: https://fastapi.tiangolo.com/advanced/websockets/
+    - [FastAPI server-sent events](https://fastapi.tiangolo.com/advanced/server-sent-events/)
+    - [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)

docs/skills/nicegui/references/source-documentation.md

@@ -4,32 +4,37 @@ Use these links for framework-specific details.
 
 ## FastAPI
 
-- FastAPI lifespan events: https://fastapi.tiangolo.com/advanced/events/
+!!! info "FastAPI sources"
-- FastAPI settings and environment variables: https://fastapi.tiangolo.com/advanced/settings/
+    - [Lifespan events](https://fastapi.tiangolo.com/advanced/events/)
-- FastAPI dependencies with yield: https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/
+    - [Settings and environment variables](https://fastapi.tiangolo.com/advanced/settings/)
-- FastAPI SQL databases tutorial: https://fastapi.tiangolo.com/tutorial/sql-databases/
+    - [Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/)
+    - [SQL databases tutorial](https://fastapi.tiangolo.com/tutorial/sql-databases/)
 
 ## SQLAlchemy and Alembic
 
-- SQLAlchemy engine configuration and pooling: https://docs.sqlalchemy.org/en/20/core/engines.html
+!!! info "Persistence sources"
-- SQLAlchemy session lifecycle basics: https://docs.sqlalchemy.org/en/20/orm/session_basics.html
+    - [SQLAlchemy engine configuration and pooling](https://docs.sqlalchemy.org/en/20/core/engines.html)
-- Alembic tutorial: https://alembic.sqlalchemy.org/en/latest/tutorial.html
+    - [SQLAlchemy session lifecycle basics](https://docs.sqlalchemy.org/en/20/orm/session_basics.html)
+    - [Alembic tutorial](https://alembic.sqlalchemy.org/en/latest/tutorial.html)
 
 ## Pydantic
 
-- Pydantic settings management: https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/
+!!! info "Pydantic source"
+    - [Pydantic settings management](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)
 
 ## NiceGUI
 
-- NiceGUI pages/routing and FastAPI integration: https://www.nicegui.io/documentation/section_pages_routing
+!!! info "NiceGUI sources"
-- NiceGUI security best practices: https://www.nicegui.io/documentation/section_security
+    - [Pages, routing, and FastAPI integration](https://www.nicegui.io/documentation/section_pages_routing)
+    - [Security best practices](https://www.nicegui.io/documentation/section_security)
 
 ## LangGraph
 
-- LangGraph overview: https://docs.langchain.com/oss/python/langgraph/overview
+!!! info "LangGraph sources"
-- LangGraph quickstart: https://docs.langchain.com/oss/python/langgraph/quickstart
+    - [Overview](https://docs.langchain.com/oss/python/langgraph/overview)
-- LangGraph workflows and agents: https://docs.langchain.com/oss/python/langgraph/workflows-agents
+    - [Quickstart](https://docs.langchain.com/oss/python/langgraph/quickstart)
-- LangGraph persistence: https://docs.langchain.com/oss/python/langgraph/persistence
+    - [Workflows and agents](https://docs.langchain.com/oss/python/langgraph/workflows-agents)
-- LangGraph memory concepts: https://docs.langchain.com/oss/python/concepts/memory
+    - [Persistence](https://docs.langchain.com/oss/python/langgraph/persistence)
-- LangGraph streaming: https://docs.langchain.com/oss/python/langgraph/streaming
+    - [Memory concepts](https://docs.langchain.com/oss/python/concepts/memory)
-- LangGraph interrupts and human-in-the-loop: https://docs.langchain.com/oss/python/langgraph/interrupts
+    - [Streaming](https://docs.langchain.com/oss/python/langgraph/streaming)
+    - [Interrupts and human-in-the-loop](https://docs.langchain.com/oss/python/langgraph/interrupts)

docs/skills/pytest-scaffolding/references/pytest-docs.md

@@ -1,11 +1,11 @@
 # Pytest Documentation Notes
 
-Primary references used:
+!!! info "Primary sources"
-- https://docs.pytest.org/en/stable/explanation/goodpractices.html
+    - [Good integration practices](https://docs.pytest.org/en/stable/explanation/goodpractices.html)
-- https://docs.pytest.org/en/stable/how-to/fixtures.html
+    - [Fixture how-to](https://docs.pytest.org/en/stable/how-to/fixtures.html)
-- https://docs.pytest.org/en/stable/example/markers.html
+    - [Marker examples](https://docs.pytest.org/en/stable/example/markers.html)
-- https://docs.pytest.org/en/stable/reference/customize.html
+    - [Configuration reference](https://docs.pytest.org/en/stable/reference/customize.html)
-- https://docs.pytest.org/en/stable/explanation/flaky.html
+    - [Flaky tests](https://docs.pytest.org/en/stable/explanation/flaky.html)
 
 ## Practical Guidance For This Skill
 - Use src-aligned test layout and keep test discovery conventional.

docs/skills/python-logging-dictconfig/SKILL.md

@@ -9,7 +9,7 @@ argument-hint: 'Target context (single script, package, FastAPI app, or CLI) and
 Use this skill to produce a minimal, centralized logging setup using `logging.config.dictConfig`.
 
 Load references only when needed:
-- Python logging overview and hierarchy: [./references/python-logging-docs.md](./references/python-logging-docs.md)
+- Python logging overview and hierarchy: [Python logging references](./references/python-logging-docs.md)
 
 ## When to Use
 - A project configures logging ad hoc with `basicConfig` across multiple modules.

docs/skills/python-logging-dictconfig/references/python-logging-docs.md

@@ -3,14 +3,18 @@
 Use these official Python docs when applying this skill.
 
 ## Core Documentation
-- Logging HOWTO: https://docs.python.org/3/howto/logging.html
+
-- Logging Cookbook: https://docs.python.org/3/howto/logging-cookbook.html
+!!! info "Core documentation"
-- logging API reference: https://docs.python.org/3/library/logging.html
+    - [Logging HOWTO](https://docs.python.org/3/howto/logging.html)
-- logging.config reference: https://docs.python.org/3/library/logging.config.html
+    - [Logging Cookbook](https://docs.python.org/3/howto/logging-cookbook.html)
+    - [logging API reference](https://docs.python.org/3/library/logging.html)
+    - [logging.config reference](https://docs.python.org/3/library/logging.config.html)
 
 ## dictConfig-Specific
-- Dictionary schema details (`version`, formatters, handlers, loggers, root): https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
+
-- `logging.config.dictConfig` function: https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig
+!!! info "dictConfig references"
+    - [Dictionary schema details](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema) for `version`, formatters, handlers, loggers, and root.
+    - [`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig) function reference.
 
 ## Practical Notes
 - Prefer app-level centralized config with one startup call to `dictConfig`.

docs/skills/zensical-docs/SKILL.md

@@ -24,38 +24,38 @@ Use this as a compact reference for Zensical mechanics and as the place to recor
 
 Open only what you need:
 
-- Official docs and source map: [./references/index.md](./references/index.md)
+- Official docs and source map: [source map](./references/index.md)
-- Zensical feature catalog and setup links: [./references/zensical-features.md](./references/zensical-features.md)
+- Zensical feature catalog and setup links: [feature catalog](./references/zensical-features.md)
-- Theme, icons, and visual customization: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
+- Theme, icons, and visual customization: [theme customization](./references/theme-customization-and-icons.md)
-- Writing quality and review criteria: [./references/documentation-quality.md](./references/documentation-quality.md)
+- Writing quality and review criteria: [documentation quality](./references/documentation-quality.md)
-- Navigation and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
+- Navigation and discoverability patterns: [discoverability and IA](./references/discoverability-and-ia.md)
-- Code-heavy docs and API reference patterns: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
+- Code-heavy docs and API reference patterns: [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md)
 
 ## Common Cases
 
 ### New docs project
 
 - Start with `uv run zensical new`.
-- Then review [./references/index.md](./references/index.md) and [./references/zensical-features.md](./references/zensical-features.md).
+- Then review the [source map](./references/index.md) and [feature catalog](./references/zensical-features.md).
 
 ### Restructuring docs or navigation
 
-- Review [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md).
+- Review [discoverability and IA](./references/discoverability-and-ia.md).
 - Use it to decide overview pages, section structure, and cross-linking.
 
 ### Improving writing quality
 
-- Review [./references/documentation-quality.md](./references/documentation-quality.md).
+- Review [documentation quality](./references/documentation-quality.md).
 - Use it for page quality gates, trust signals, and review criteria.
 
 ### Adjusting theme or UI mechanics
 
-- Review [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md).
+- Review [theme customization](./references/theme-customization-and-icons.md).
 - Use it for icons, color, theme extensions, and presentation choices.
 
 ### Documenting APIs or code-heavy systems
 
-- Review [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md).
+- Review [code-heavy docs](./references/code-heavy-docs-and-mkdocstrings.md).
 - Use it when generated API reference belongs alongside hand-authored docs.
 
 ## Preferences To Maintain Here

docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md

@@ -6,10 +6,10 @@ Use this reference when your docs include API surfaces, function/class documenta
 
 mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.
 
-Primary docs:
+!!! info "Primary docs"
-- mkdocstrings home: https://mkdocstrings.github.io/
+   - [mkdocstrings home](https://mkdocstrings.github.io/)
-- mkdocstrings Python handler: https://mkdocstrings.github.io/python/
+   - [mkdocstrings Python handler](https://mkdocstrings.github.io/python/)
-- Griffe (Python parsing engine): https://mkdocstrings.github.io/griffe/
+   - [Griffe Python parsing engine](https://mkdocstrings.github.io/griffe/)
 
 ## When to Use It
 
@@ -32,13 +32,13 @@ Primary docs:
 3. Create one API index page per package/domain.
 4. Expand coverage gradually from high-value modules first.
 
-General reference examples:
+!!! info "General reference examples"
-- Zensical docs home and setup entry point: https://zensical.org/docs/
+    - [Zensical docs home and setup entry point](https://zensical.org/docs/)
-- Zensical code blocks and authoring patterns: https://zensical.org/docs/authoring/code-blocks/
+    - [Zensical code blocks and authoring patterns](https://zensical.org/docs/authoring/code-blocks/)
-- Zensical customization overview: https://zensical.org/docs/customization/
+    - [Zensical customization overview](https://zensical.org/docs/customization/)
 
-Compatibility note:
+!!! note "Compatibility"
-- Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
+    Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
 
 ## Authoring Guidance for Docstrings
 

docs/skills/zensical-docs/references/discoverability-and-ia.md

@@ -13,9 +13,9 @@ Recommended top-level model:
 3. Reference (API, config, command catalog)
 4. Troubleshoot (symptoms, diagnostics, fixes)
 
-References:
+!!! info "IA references"
-- Diataxis framework: https://diataxis.fr/
+    - [Diataxis framework](https://diataxis.fr/)
-- Divio documentation system: https://documentation.divio.com/
+    - [Divio documentation system](https://documentation.divio.com/)
 
 ## Progressive Discoverability Pattern
 
@@ -47,11 +47,11 @@ Keep deep details in dedicated reference pages and link to them from task pages
 3. Place high-frequency tasks near the top.
 4. Keep section depth shallow where possible.
 
-Relevant Zensical configuration docs:
+!!! info "Relevant Zensical configuration docs"
-- Navigation: https://zensical.org/docs/setup/navigation/
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
-- Search: https://zensical.org/docs/setup/search/
+    - [Search setup](https://zensical.org/docs/setup/search/)
-- Header: https://zensical.org/docs/setup/header/
+    - [Header setup](https://zensical.org/docs/setup/header/)
-- Footer: https://zensical.org/docs/setup/footer/
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
 
 ## Link Strategy
 

docs/skills/zensical-docs/references/documentation-quality.md

@@ -10,10 +10,10 @@ Use this reference when writing or reviewing docs for clarity, correctness, and
 4. Make examples executable and verifiable.
 5. Prefer precise language over marketing language.
 
-Primary references:
+!!! info "Primary references"
-- Diataxis: https://diataxis.fr/
+    - [Diataxis](https://diataxis.fr/)
-- Divio documentation system: https://documentation.divio.com/
+    - [Divio documentation system](https://documentation.divio.com/)
-- Write the Docs guide: https://www.writethedocs.org/guide/
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
 
 ## Style and Readability
 
@@ -22,10 +22,10 @@ Primary references:
 - Prefer active voice and imperative instructions for task pages.
 - Add notes/warnings only for high-impact caveats.
 
-Source links:
+!!! info "Style sources"
-- Google developer style: https://developers.google.com/style
+    - [Google developer style](https://developers.google.com/style)
-- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
-- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
 
 ## Task Page Quality Pattern
 

docs/skills/zensical-docs/references/index.md

@@ -4,40 +4,43 @@ Use this index to load only the source references needed for the current task.
 
 ## Zensical Official Docs
 
-- New project scaffolding (`uv run zensical new`): https://zensical.org/docs/
+!!! info "Zensical official docs"
-- Home: https://zensical.org/docs/
+    - [New project scaffolding](https://zensical.org/docs/) for `uv run zensical new`.
-- Setup basics: https://zensical.org/docs/setup/basics/
+    - [Home](https://zensical.org/docs/)
-- Navigation setup: https://zensical.org/docs/setup/navigation/
+    - [Setup basics](https://zensical.org/docs/setup/basics/)
-- Header setup and announcement bar: https://zensical.org/docs/setup/header/
+    - [Navigation setup](https://zensical.org/docs/setup/navigation/)
-- Footer setup: https://zensical.org/docs/setup/footer/
+    - [Header setup and announcement bar](https://zensical.org/docs/setup/header/)
-- Repository and content actions: https://zensical.org/docs/setup/repository/
+    - [Footer setup](https://zensical.org/docs/setup/footer/)
-- Search setup: https://zensical.org/docs/setup/search/
+    - [Repository and content actions](https://zensical.org/docs/setup/repository/)
-- Customization overview: https://zensical.org/docs/customization/
+    - [Search setup](https://zensical.org/docs/setup/search/)
-- Additional CSS: https://zensical.org/docs/customization/#additional-css
+    - [Customization overview](https://zensical.org/docs/customization/)
-- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
-- Theme extension and overrides: https://zensical.org/docs/customization/#extending-the-theme
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
-- Language setup: https://zensical.org/docs/setup/language/
+    - [Theme extension and overrides](https://zensical.org/docs/customization/#extending-the-theme)
-- Logo and icons: https://zensical.org/docs/setup/logo-and-icons/
+    - [Language setup](https://zensical.org/docs/setup/language/)
-- Code blocks and annotations: https://zensical.org/docs/authoring/code-blocks/
+    - [Logo and icons](https://zensical.org/docs/setup/logo-and-icons/)
-- Content tabs: https://zensical.org/docs/authoring/content-tabs/
+    - [Code blocks and annotations](https://zensical.org/docs/authoring/code-blocks/)
-- Footnotes: https://zensical.org/docs/authoring/footnotes/
+    - [Content tabs](https://zensical.org/docs/authoring/content-tabs/)
-- Tooltips: https://zensical.org/docs/authoring/tooltips/
+    - [Footnotes](https://zensical.org/docs/authoring/footnotes/)
+    - [Tooltips](https://zensical.org/docs/authoring/tooltips/)
 
 ## Adjacent Documentation Quality Sources
 
-- Divio documentation system: https://documentation.divio.com/
+!!! info "Documentation quality sources"
-- Write the Docs guide: https://www.writethedocs.org/guide/
+    - [Divio documentation system](https://documentation.divio.com/)
-- Google developer documentation style guide: https://developers.google.com/style
+    - [Write the Docs guide](https://www.writethedocs.org/guide/)
-- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/welcome/
+    - [Google developer documentation style guide](https://developers.google.com/style)
-- MDN writing guidelines: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines
+    - [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/)
-- Diataxis framework: https://diataxis.fr/
+    - [MDN writing guidelines](https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines)
+    - [Diataxis framework](https://diataxis.fr/)
 
 ## Related Tooling References
 
-- Markdown guide: https://www.markdownguide.org/
+!!! info "Related tooling"
-- Zensical setup and configuration entry point: https://zensical.org/docs/
+    - [Markdown guide](https://www.markdownguide.org/)
-- Zensical customization reference: https://zensical.org/docs/customization/
+    - [Zensical setup and configuration entry point](https://zensical.org/docs/)
-- mkdocstrings: https://mkdocstrings.github.io/
+    - [Zensical customization reference](https://zensical.org/docs/customization/)
+    - [mkdocstrings](https://mkdocstrings.github.io/)
 
 ## Skill-Specific Deep Dives
 

docs/skills/zensical-docs/references/theme-customization-and-icons.md

@@ -15,11 +15,12 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
 
 ## Key Zensical Customization Surfaces
 
-- Customization overview: https://zensical.org/docs/customization/
+!!! info "Zensical sources"
-- Additional CSS: https://zensical.org/docs/customization/#additional-css
+    - [Customization overview](https://zensical.org/docs/customization/)
-- Additional JavaScript: https://zensical.org/docs/customization/#additional-javascript
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
-- Extending the theme: https://zensical.org/docs/customization/#extending-the-theme
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
-- Logo and icons setup: https://zensical.org/docs/setup/logo-and-icons/
+    - [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
+    - [Logo and icons setup](https://zensical.org/docs/setup/logo-and-icons/)
 
 ## Colors and Accessibility
 
@@ -27,21 +28,22 @@ Always start new projects with `uv run zensical new` so the baseline theme/confi
 - Keep contrast high for body text, code blocks, and nav labels.
 - Test color changes on mobile and desktop, including search highlights and active nav states.
 
-General references:
+!!! info "General references"
-- Material design color guidance: https://m3.material.io/styles/color
+    - [Material Design color guidance](https://m3.material.io/styles/color)
-- WCAG overview: https://www.w3.org/WAI/standards-guidelines/wcag/
+    - [WCAG overview](https://www.w3.org/WAI/standards-guidelines/wcag/)
 
 ## Icons: Selection and Search Landing Pages
 
 If your theme supports icon sets through your docs stack, these search portals are useful:
 
-- Material Symbols search: https://fonts.google.com/icons
+- [Material Symbols search](https://fonts.google.com/icons)
-- Font Awesome icons search: https://fontawesome.com/search
+- [Font Awesome icons search](https://fontawesome.com/search)
-- Simple Icons search: https://simpleicons.org/
+- [Simple Icons search](https://simpleicons.org/)
-- Iconify icon set search: https://icon-sets.iconify.design/
+- [Iconify icon set search](https://icon-sets.iconify.design/)
-- Lucide icons: https://lucide.dev/icons/
+- [Lucide icons](https://lucide.dev/icons/)
 
-Tip: pick one primary icon family for navigation and status icons, then document naming conventions.
+!!! tip "Icon family consistency"
+    Pick one primary icon family for navigation and status icons, then document naming conventions.
 
 ## Extending the Theme Safely
 

docs/skills/zensical-docs/references/zensical-features.md

@@ -21,8 +21,8 @@ Always start a new docs project with `uv run zensical new`.
 - `navigation.top`: shows a back-to-top affordance.
 - `navigation.tracking`: keeps URL anchors in sync with active section.
 
-Source links:
+!!! info "Source links"
-- https://zensical.org/docs/setup/navigation/
+    - [Zensical navigation setup](https://zensical.org/docs/setup/navigation/)
 
 ### Code-Heavy Documentation
 
@@ -32,9 +32,9 @@ Source links:
 - Prefer mkdocstrings for generated API reference pages when documenting Python code.
 - Keep generated API pages linked from hand-authored task and concept docs.
 
-Source links:
+!!! info "Source links"
-- https://zensical.org/docs/authoring/code-blocks/
+    - [Zensical code blocks](https://zensical.org/docs/authoring/code-blocks/)
-- https://mkdocstrings.github.io/
+    - [mkdocstrings](https://mkdocstrings.github.io/)
 
 ### Cross-Page UX Consistency
 
@@ -42,19 +42,19 @@ Source links:
 - `content.tooltips`: improves tooltip behavior for links.
 - `content.footnote.tooltips`: inline footnote previews.
 
-Source links:
+!!! info "Source links"
-- https://zensical.org/docs/authoring/content-tabs/
+    - [Zensical content tabs](https://zensical.org/docs/authoring/content-tabs/)
-- https://zensical.org/docs/authoring/tooltips/
+    - [Zensical tooltips](https://zensical.org/docs/authoring/tooltips/)
-- https://zensical.org/docs/authoring/footnotes/
+    - [Zensical footnotes](https://zensical.org/docs/authoring/footnotes/)
 
 ### Search and Content Actions
 
 - `search.highlight`: highlights matches after search navigation.
 - `content.action.edit` and `content.action.view` (if repository integration is configured).
 
-Source links:
+!!! info "Source links"
-- https://zensical.org/docs/setup/search/
+    - [Zensical search setup](https://zensical.org/docs/setup/search/)
-- https://zensical.org/docs/setup/repository/
+    - [Zensical repository setup](https://zensical.org/docs/setup/repository/)
 
 ## Styling and Extensibility
 
@@ -64,11 +64,11 @@ Use site-level customization when docs need stronger visual affordances.
 - `extra_javascript`: add behavior enhancements.
 - Theme override directory (`custom_dir`) for template-level changes.
 
-Source links:
+!!! info "Source links"
-- https://zensical.org/docs/customization/
+    - [Zensical customization overview](https://zensical.org/docs/customization/)
-- https://zensical.org/docs/customization/#additional-css
+    - [Additional CSS](https://zensical.org/docs/customization/#additional-css)
-- https://zensical.org/docs/customization/#additional-javascript
+    - [Additional JavaScript](https://zensical.org/docs/customization/#additional-javascript)
-- https://zensical.org/docs/customization/#extending-the-theme
+    - [Extending the theme](https://zensical.org/docs/customization/#extending-the-theme)
 
 ## Practical Feature Selection Rules