Cursor integration

Use Eko Common Docs from Cursor in application repositories so agents follow shared standards and patterns.

Prerequisites

• Docs are built and published (just build, then deploy site/).
• site_url in the repository root mkdocs.yml matches your deployed base URL (trailing slash required).
• Stable page URLs follow MkDocs paths: docs/patterns/foo.md → {site_url}patterns/foo/.

Current base URL is set as site_url in the repository root mkdocs.yml (default: https://ekotools.codeberg.page/docs/).

Option A — Indexed docs (quick)

1. Open Cursor Settings → Indexing → Docs (label may vary by version).
2. Add your deployed docs root, e.g. https://ekotools.codeberg.page/docs/.
3. In chat, type @ and select that doc source, then ask your question.

Example prompt: “Implement list pagination per our Eko docs (@Eko Common Docs).”

Limitations: Private or auth-walled sites may not index. HTML pages are less reliable than local markdown. Use Options B or C for must-follow standards.

Option B — Project rules (recommended)

Add a rule file in each application repo: .cursor/rules/eko-standards.mdc.

Use globs for the stacks you care about (**/*.py, **/api/**, etc.). Keep rules short; link to hosted pages for full text.

Template (copy into consuming projects and adjust globs):

---
description: Eko shared standards and patterns
globs: "**/*.py"
alwaysApply: false
---

# Eko documentation

Follow org standards from Eko Common Docs:

- Python projects: {BASE}standards/python/python-project-standards/
- Common tasks (justfile, VS Code): {BASE}standards/common/tasks/
- Configuration pattern: {BASE}patterns/configuration/
- Pagination pattern: {BASE}patterns/pagination/
- Cursor setup: {BASE}cursor-integration/

When implementing config, lists, or project layout, open the relevant page before changing code.

Replace {BASE} with your site_url from mkdocs.yml.

Option C — Submodule (best fidelity)

Pin this repo inside an application workspace so the agent reads the same markdown MkDocs builds:

git submodule add ssh://git@codeberg.org/ekotools/docs.git vendor/eko-docs

In chat or rules, reference files directly:

• @vendor/eko-docs/docs/patterns/pagination.md
• @vendor/eko-docs/docs/standards/python/python-project-standards.md

Update the submodule when standards change.

URL map

Topic	Source	Hosted path (under site_url)
Cursor integration	docs/cursor-integration.md	cursor-integration/
Configuration	docs/patterns/configuration.md	patterns/configuration/
Pagination	docs/patterns/pagination.md	patterns/pagination/
Python standards	docs/standards/python/python-project-standards.md	standards/python/python-project-standards/
Common tasks	docs/standards/common/tasks.md	standards/common/tasks/

Prompt examples

• “Scaffold pyproject.toml per @vendor/eko-docs/docs/standards/python/python-project-standards.md.”
• “Add list API pagination per {BASE}patterns/pagination/.”
• “Use frontend/backend/project config split per {BASE}patterns/configuration/.”

Rules in this repository

When editing docs here, .cursor/rules/eko-docs-authoring.mdc reminds the agent where standards and patterns live. That rule applies in this repo only; copy Option B into application repos for enforcement there.

Maintenance

1. Change standards or patterns under docs/.
2. Run just build and deploy.
3. Re-index Cursor Docs if you use Option A.
4. Bump submodules in consuming repos if you use Option C.