formatting

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) |
-| Session factory and scope | [references/session.md](references/session.md) |
-| Transaction boundaries | [references/transactions.md](references/transactions.md) |
-| Lifespan composition | [references/engine.md](references/engine.md) |
-| Dependency injection | [references/session.md](references/session.md) |
-| Implicit I/O control in ORM | [references/implicit_io.md](references/implicit_io.md) |
-| Observability and resilience | [references/observability.md](references/observability.md) |
+| Engine lifecycle and ownership | [Engine lifecycle reference](references/engine.md) |
+| Session factory and scope | [Session management reference](references/session.md) |
+| Transaction boundaries | [Transaction boundaries reference](references/transactions.md) |
+| Lifespan composition | [Engine lifecycle reference](references/engine.md) |
+| Dependency injection | [Session management reference](references/session.md) |
+| Implicit I/O control in ORM | [Implicit I/O reference](references/implicit_io.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
-- 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
+!!! info "Primary sources"
+   - [SQLAlchemy engine and connections](https://docs.sqlalchemy.org/en/21/core/connections.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)