doc updates

src/personal_mcp/docs/testing.md

@@ -4,96 +4,44 @@ icon: lucide/flask-conical
 
 # Testing
 
-This page describes the current test layout and execution model for this repository.
-
-Primary guidance sources:
-- [Pytest scaffolding skill](./skills/pytesting/SKILL.md)
-- [Pytest docs reference](./skills/pytesting/references/pytest-docs.md)
-- [FastAPI + uv + Docker skill](./skills/fastapi-uv-docker/SKILL.md)
-
-## Goals
-
-1. Keep local feedback fast with deterministic tests.
-2. Mirror source modules with focused test groups.
-3. Keep endpoint and MCP surface checks explicit.
-4. Make marker usage strict and intentional.
+The test suite checks that the same public MCP behavior works over HTTP and stdio.
 
 ## Current Test Layout
 
-Current tree:
-
 ```text
 tests/
-    __init__.py
     conftest.py
-    registry/
-        test_read.py
-        ingest/
-            test_current_docs.py
-            test_document.py
-        models/
-            test_document_validation.py
-    prompts/
-        test_content_renderer.py
-        test_filesystem_provider.py
-    skills/
-        test_provider.py
-    web/
-        conftest.py
-        test_endpoint_connections.py
-        test_mcp_prompts.py
-        test_mcp_skills.py
+    server_contract.py
+    test_http.py
+    test_stdio.py
 ```
 
-Source-to-test alignment today:
-- `src/personal_mcp/registry/ingest/` -> `tests/registry/ingest/`
-- `src/personal_mcp/registry/models/` -> `tests/registry/models/`
-- `src/personal_mcp/prompts/` -> `tests/prompts/`
-- `src/personal_mcp/skills/provider.py` -> `tests/skills/test_provider.py`
-- `src/personal_mcp/web/` and MCP HTTP surface -> `tests/web/`
+`server_contract.py` contains the shared expectations. Both transport tests verify the resources, prompts, fallback tools, and representative reads against that contract.
 
-## Markers And Strictness
+## Run Tests
 
-Configured markers in `pyproject.toml`:
-- `unit`: fast deterministic tests with no external dependencies
-- `integration`: framework or component integration tests
-- `smoke`: thin critical-path checks
-
-Pytest runs with `--strict-markers`, so any unregistered marker fails the test run.
-
-## Fixture Layering
-
-Fixture placement follows test scope:
-1. `tests/conftest.py` for cross-suite defaults.
-2. `tests/web/conftest.py` for web and endpoint client setup.
-
-Prefer adding fixtures at the narrowest scope that serves more than one test.
-
-## Command Baseline
-
-Canonical invocation:
+Run the full suite with:
 
 ```bash
 uv run pytest
 ```
 
-Useful filtered runs:
+Run one transport while working on a focused change:
 
 ```bash
-uv run pytest --collect-only -q
-uv run pytest -m unit -q
-uv run pytest -m integration -q
-uv run pytest -m smoke -q
+uv run pytest tests/test_http.py -q
+uv run pytest tests/test_stdio.py -q
 ```
 
-## Adding New Tests
+The repository uses strict pytest markers. Register any new marker in `pyproject.toml` before using it.
 
-When adding coverage:
-1. Place tests under the nearest existing module subtree (`prompts/`, `registry/`, `skills/`, or `web/`).
-2. Mirror the source path where practical.
-3. Reuse existing `conftest.py` files before adding new fixture layers.
-4. Add markers only when they convey execution intent, and register new markers in `pyproject.toml` first.
+## Full Validation
 
-This keeps the suite aligned with the current architecture while preserving a fast local test loop.
+```bash
+uv run zensical build
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
 
-Prefer durable boundaries over implementation details: provider discovery, prompt rendering, traversal rejection, protocol behavior, and installed-package path resolution. Do not test deleted catalog projections, Pydantic immutability internals, or helper delegation.
+See the [Pytesting skill](./skills/pytesting/SKILL.md) when adding or restructuring tests.