Portfolio Workflows

Local-first portfolio, with GitHub when you want it.

DollhouseMCP keeps your elements in a local portfolio first. GitHub sync, backup, and community submission are optional workflows layered on top, not requirements for getting value out of the platform.

Works immediately offline

Your portfolio lives in ~/.dollhouse/portfolio/, so you can create, activate, and edit elements without creating an account.

GitHub as backup and sync

When you are ready, you can authenticate with GitHub, initialize a portfolio repo, and synchronize changes across machines.

Share back to the Collection

Portfolio workflows also support submitting elements to the community collection when something becomes broadly useful.

Readable files, not hidden state

Elements remain inspectable markdown or YAML instead of disappearing into chat history or proprietary storage.

Core portfolio operations

Operation	Endpoint	Purpose
`check_github_auth`	Read	Verify current GitHub authentication status.
`setup_github_auth`	Create	Start the OAuth device flow.
`init_portfolio`	Create	Create the GitHub portfolio repository.
`portfolio_status`	Read	Inspect repository existence, URLs, and element counts.
`portfolio_element_manager`	Create	Upload, download, list, or compare individual elements.
`sync_portfolio`	Create	Bulk sync between local portfolio and GitHub.
`submit_collection_content`	Create	Submit an element to the community Collection.

Core GitHub portfolio flow

Check GitHub auth
Verify authentication or start the OAuth setup flow directly through DollhouseMCP.
Initialize the repo
Create a dedicated portfolio repository and seed the standard element directories.
Push or pull elements
Upload individual elements, bulk sync changes, or mirror updates conservatively with dry-run support.
Submit to the Collection
Move from private portfolio use to community distribution when a building block is ready to share.

Repository layout

There are two related layouts here. The first is the local filesystem portfolio that works immediately on your machine. The second is the optional GitHub portfolio repository created by init_portfolio so you can sync, back up, and share across devices.

Local portfolio on disk

~/.dollhouse/
  portfolio/
    personas/
    skills/
    templates/
    agents/
    memories/
    ensembles/
  config/
  logs/

GitHub portfolio repository mirror

dollhouse-portfolio/
  personas/
    creative-writer.md
    technical-analyst.md
  skills/
    code-review.md
    research.md
  templates/
    meeting-notes.md
  agents/
    session-monitor.md
  memories/
    project-context.yaml
  ensembles/
    dollhouse-expert-suite.md
  README.md

The GitHub repository mirrors the local portfolio model directly. That matters because the local layout, the optional GitHub backup/sync layout, and the activation model all stay aligned instead of drifting into separate abstractions.

Operational details

Dry runs and conservative sync
sync_portfolio supports dry-run and additive modes so you can inspect changes before pushing or pulling in bulk.
Portfolio browser support
open_portfolio_browser exposes the local portfolio visually at a localhost UI while the underlying files stay readable on disk.
Search stays unified
search_portfolio and search_all let you search across local, GitHub, and collection sources rather than treating each surface as isolated.
Config is explicit
portfolio_config supports options like auto_sync, auto_submit, and custom repository naming instead of burying those choices in app state.

The portfolio model is intentionally additive: you do not need GitHub to use DollhouseMCP, but GitHub becomes a strong upgrade path for backup, collaboration, and distribution.