sugg: Ensure docs are current and complete by unifying with code

[planetf1]

Proposal: Unify Documentation and Code into Single Repository (Mintlify)

As a new contributor just getting started with Mellea, I noticed some places where the docs website has drifted from the code in this repo.

The Problem

Docs are maintained in a separate repo (generative-computing/docs), which creates friction that leads to the website falling behind.

Specific Examples :

• Safety Warnings: The local tutorial.md (Chapter 4) warns about "untrusted code execution", but this critical warning is missing from the website.
• API Drift: The start_session function in session.py has a model_options argument that is missing from the website API reference.
• Tech Debt: The split repo encourages merging code without docs. Issue [Tutorial] Add a section in the Context Management on Elron's context manager session feature. #73 explicitly states "merge for now, so that we're not gating a new feature on docs"—a pattern that creates debt.
• Missed Examples: Issue Suggestion: Add a "mify objects" example to tutorial Chapter 5 #306 notes that useful examples exist in the codebase but are missing from the tutorial, another symptom of the docs lagging behind.

Proposed Solution

Move to a Single Repo model (like AgentStack):

1. Migrate Config: Move docs.json (renaming to mintlify.json) into mellea/docs/.
2. Consolidate: Serve docs directly from the docs/ folder here.
3. Update Dashboard: Point Mintlify to generative-computing/mellea.
4. Archive: Deprecate the old docs repo.

Benefits

• Atomic Updates: Documentation updates happen in the same PR as the code change.
• No "Follow-up" Issues: We stop creating issues like [Tutorial] Add a section in the Context Management on Elron's context manager session feature. #73. If a feature lands, the docs land with it.
• PR Review: Reviewers can see the docs diff right alongside the code diff.
• Accuracy: Users always see the API signatures and safety warnings that match the installed package.

Note

• Additional Repos: We do also have contribs/extras. We'd need to sync/copy content if we wanted to integrate in main repos. On balance I still think the proposal here makes sense as it focusses on the core - and we can revisit later if needed.

I'd be happy to help 🚀

[jakelorocco]

Thank you @planetf1; @mishaldholakia is working on updating the doc generation scripts and moving everything into the main repo. This should at least keep our docs up to date with the latest pypi release. This doesn't cover everything in this issue, but it should get us moving in that direction.

[planetf1]

Thanks. that's great to know it's being worked on.

[planetf1]

this can be closed now after doc improvements and automation