Docs fixes for developers

[leshy]

can't find a link to how to develop (checkout) the repo on main README.MD

when I go into https://github.com/dimensionalOS/dimos/tree/main/docs/development

I don't have index.md, and IDK where to click

I don't even know how to check out the repo, run mypy?

---

Synced from DIM-894 by summer

[spomichter]

Yeah need a full docs audit and review on current main branch. Needs design cleanup and then mirror on mintlify if you want to own this @swstica

@leshy Dev instructions are in the main README just at the bottom maybe need to raise up

[spomichter]

Daneel can you propose a minimal spec

[dimos-bot]

Stash (via Linear):

Spec: DIM-894 — Docs fixes for developers

Problem

1. No entry point for docs/development/ — there's no index.md, so navigating to the directory on GitHub shows a raw file list with no guidance on where to start.
2. README.md's Development section is too thin — it has a 3-line clone-and-test snippet but doesn't link to a developer setup guide, mypy, linting, pre-commit, or the existing docs/development/ pages.
3. No CONTRIBUTING.md — no standard contributing guide exists at the repo root.
4. Key developer workflows are undocumented: How to set up the dev environment, run mypy, run ruff/linting, configure pre-commit hooks, understand project structure.

Existing docs in docs/development/

File	Content
testing.md	pytest usage, markers, fixtures, mocking (good)
conventions.md	Coding conventions (brief)
writing_docs.md	How to write docs
docker.md	Docker image hierarchy
grid_testing.md	Advanced grid testing patterns
large_file_management.md	LFS data loading (get_data)
profiling_dimos.md	py-spy profiling

All good content, but no index ties them together and several key topics are missing entirely.

Proposed Changes

1. Create docs/development/index.md — Developer Guide entry point

A comprehensive page covering:

• Cloning the repo — GIT_LFS_SKIP_SMUDGE=1 git clone ... (and why)
• Setting up the dev environment — uv sync --extra all (or --all-groups for full dev), activating the venv
• Pre-commit hooks — pre-commit install (auto-runs ruff-format, ruff-check, license headers, editorconfig, trailing whitespace, JSON/TOML/YAML checks)
• Running linters — ruff check dimos/, ruff format dimos/
• Running mypy — mypy dimos/ (strict mode, stubs/ path, Python 3.12)
• Running tests — brief summary + link to testing.md
• Project structure overview — key directories (dimos/, docs/, data/, bin/, blueprints/, stubs/)
• Table of other dev docs — links to all existing docs/development/*.md pages

2. Update README.md Development section

Expand from the current 3-line snippet to:

• Keep the quick clone + test snippet
• Add explicit links: "For the full developer guide, see docs/development/index.md"
• Add a brief mention of pre-commit install, mypy, ruff with link to the index

3. Scope boundaries (NOT doing)

• Not creating a full CONTRIBUTING.md — that's a separate concern (PR etiquette, issue templates, etc.)
• Not restructuring existing docs — just adding the missing entry point and links
• Not documenting CI/CD pipelines — separate issue

Estimated diff

• New file: docs/development/index.md (~120-150 lines)
• Edit: README.md Development section (~10-15 lines changed)
• Total: ~2 files changed, minimal risk

Questions

• Should the developer index also cover the dimos CLI for development (dimos list, dimos run --daemon, etc.), or keep that in docs/usage/cli.md?
• Any preference on whether to mention IDE setup (VSCode settings, recommended extensions)?

Waiting for approval before implementing.

‌‌‌

[spomichter]

sure yeah you can open a PR along these lines. keep minimal. No CLI stuff in deveopment i think we already have a cli.md. Format it nicely i can send you some good open source repos that do this well. @swstica Im sure you have some good inspiration from other reops we can use as a guide

[dimos-bot]

Stash (via Linear):
PR opened: #2141

Implemented per the approved spec with feedback incorporated:

• Minimal — docs/development/index.md (~107 lines): clone → deps → pre-commit → linting → mypy → testing → project structure → links to existing dev docs
• No CLI stuff — just a one-line pointer to docs/usage/cli.md
• Clean formatting — section headings, fenced code blocks, project tree, summary table of further reading
• README updated — Development section now has complete setup snippet + link to full guide

Total diff: 2 files changed, +113 −6 lines.

‌‌‌

[dimos-bot]

Stash (via Linear):

📎 Reviewed the attached commit 047aa32 on branch docs/dim-894-developer-guide.

This adds docs/development/index.md — a comprehensive developer guide covering:

• Clone (with LFS skip)
• Dependency install via uv sync
• Pre-commit hook setup
• Linting (ruff format + ruff check) and type checking (mypy)
• Testing (pytest --numprocesses=auto, fast/slow scripts)
• Project structure overview
• Links to all existing dev docs (testing, docker, LFS, profiling, conventions)

The corresponding PR is #2141 — currently open, mergeable, CI running. Directly addresses Ivan's original complaint about not knowing how to check out the repo or run mypy.
‌‌‌

[dimos-bot]

Stash (via Linear):
PR #2141 attached — reviewed the diff.

Aligns with the spec: new docs/development/index.md covering clone → deps → pre-commit → linting → mypy → tests → project structure → further reading table. README Development section updated with the full setup sequence and a link to the guide. CLI docs correctly left in docs/usage/cli.md, no CONTRIBUTING.md (separate concern).

Diff is clean — 2 files, +113/−6, no risk. LGTM.

‌‌‌