Documentation Homebases

Core concepts

Homebases

A durable home for the knowledge that connects your work.

A homebase is the canonical folder of knowledge that your projects share. It lives separately from application code, so knowledge about your product or system doesn’t belong to just one repository.

Start with one homebase and a few useful Markdown pages. You don’t need an elaborate taxonomy to make shared context valuable.

Already have a home repo? Register that directory as your homebase with mindslice init /path/to/your-home-repo. Review the detected role and choose Home / homebase if prompted. You don’t need a second repository just for Mindslice.

What belongs here

Write down information that helps someone make a better decision, especially when it is hard to infer from code alone:

  • Product context: who the product serves, what it promises, and what it deliberately doesn’t do.
  • Architecture: system boundaries, responsibilities, and how applications fit together.
  • Decisions: what you chose, why, and which alternatives you ruled out.
  • Conventions: the patterns and workflows you want work to follow.
  • Operational knowledge: constraints and lessons that future work should respect.

Keep credentials, tokens, and sensitive personal information out of shared knowledge. Choose repository and filesystem permissions appropriate to the content.

Start with a simple structure

This is an example, not a required schema:

text
knowledge/
  README.md
  product/
    overview.md
  architecture/
    system.md
    decisions.md
  conventions/
    development.md

An index helps both people and agents find the right page. Use descriptive headings, link related topics, and organize around the knowledge itself rather than copying your application folder structure.

Use the home-repo pattern

The home-repo pattern brings shared documentation, agent guidance, and references to application repos into one place. Mindslice supports using that home as a starting point for context and coordination, while keeping implementation in separate application checkouts.

After connecting your applications, run these commands from the registered homebase:

Terminal
mindslice projects list --json
mindslice projects resolve --json

list shows the homebase’s known projects and cached checkout information. resolve searches locally for matching Mindslice project descriptors. This is discovery of registered projects, not an inventory of every repository on your machine.

Review each result’s status, paths, search roots, completeness, and issues. An ambiguous or missing checkout needs an explicit choice or path, not a guess. Discovery does not clone, initialize, connect, or launch anything.

Use the homebase to understand how the system fits together and decide which projects a task affects. Then work in the appropriate application directories, following their own instructions, build commands, and permissions. Keep application checkouts outside the Mindslice homebase.

Describe project responsibilities

For each project in the homebase, you can optionally record a short purpose, responsibilities, boundaries, and links to its repository instructions. From the homebase, run:

Terminal
mindslice projects edit --project-id <project-id>

An agent can use this map to shortlist likely repositories and explain its plan. It is guidance, not automatic routing: verify ownership against the project’s instructions and implementation. This metadata does not change knowledge selection, grant repository access, or launch agents.

Homebase initialization adds generic AGENTS.md guidance only if that file does not already exist. Review the optional homebase coordination skill and any project integrations before accepting them. Project context views contain selected knowledge, not an automatic copy of your home repo’s skills and steering files.

The agent workflow guide shows how to move from shared planning to project-local implementation.

A folder, with Git if you want it

A homebase can be a plain local directory. Markdown remains readable and writable without Git.

If the homebase is a Git repository, ordinary Git tools can provide history, review, and remote collaboration. Mindslice’s experimental automatic local history applies to selected service-submitted Markdown writes in an eligible Git-root homebase; it is not a watcher that commits every filesystem edit.

Automatic local history never means automatic publishing. The current CLI does not implement ongoing remote fetch/sync or publish commands. Use your normal Git workflow for those operations.

Keep one source of truth

Edit canonical knowledge in the homebase, or through an approved Mindslice change workflow. A project’s generated context view is for discovery and reading—not another documentation repository to maintain.

Keep claims small and specific. Distinguish an implemented feature from a proposal. When a behavior changes, update the relevant explanation rather than leaving contradictory pages behind.

Share knowledge deliberately

Several projects can use the same homebase, and one project can connect to more than one homebase. Use project-specific selection to keep context relevant.

Selection does not protect secrets or create an authorization boundary. Anyone with access to the underlying homebase may be able to read its contents.

Continue with project context to understand how selected knowledge reaches an application.