feat/output format

AGENTS.md

@@ -0,0 +1,32 @@
+# AGENTS.md
+
+Agent notes for working in this repository. The scope of this file is the entire repo.
+
+## Working Directory & Module Discovery
+
+- Always confirm `pwd` before running commands.
+- When testing mdxify on other projects, ensure modules are importable from CWD or run from the target project with:
+  - `uv run --with-editable /path/to/mdxify mdxify`
+- Prefer `uv run -m` over invoking Python directly.
+
+## UV Usage
+
+- Use `uv run` for scripts and tests.
+- Use `uvx mdxify@version` to test a specific PyPI version.
+
+## Testing Discipline
+
+- Run the full test suite: `uv run pytest -xvs`.
+- For navigation/output changes, validate against a real project (e.g., FastMCP).
+
+## Git & Releases
+
+- Run pre-commit before pushing: `uv run pre-commit run --all-files`.
+- Push to `main` before creating a release.
+- Create releases with `gh release create` (CI handles PyPI).
+
+## Focus
+
+- Don’t fixate on arbitrary details; align with user requirements.
+- Ask for clarification when intent isn’t clear.
+

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to mdxify
+
+Thanks for contributing! This guide outlines local development, testing, and release tips.
+
+## Local Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -xvs
+
+# Type checking
+uv run ty check
+
+# Linting
+uv run ruff check src/ tests/
+
+# Pre-commit hooks
+uv run pre-commit install
+uv run pre-commit run --all-files
+```
+
+## Working Practices
+
+- Prefer small, focused PRs with clear titles and descriptions.
+- For navigation/output changes, test on a real project (e.g., FastMCP) where possible.
+- Ask for clarification if goals are ambiguous.
+
+## Releasing
+
+- Ensure tests pass and pre-commit is clean.
+- Push to `main` before creating a release.
+- Use `gh release create` (GitHub Actions handles PyPI publishing).
+
+## Notes on Navigation Structure
+
+- Top-level groups use fully-qualified names (e.g., `fastmcp.client`).
+- Nested groups use simple names (e.g., `auth`).
+- Entries are sorted: plain pages first, then groups alphabetically.
+
+## Default Paths
+
+- Default output directory: `docs/python-sdk`
+- Default navigation anchor: `SDK Reference`
+