User Story

As an ApexYard adopter on a personal GitHub account with any private projects, I want the framework's setup flow to recommend a fork-pattern that keeps my portfolio data (registry + per-project handover docs) in a private repo, so that registering my projects under ApexYard governance does not silently publish their names on GitHub.

Driver

The current docs/multi-project.md instructs adopters to fork apexyard and commit apexyard.projects.yaml + projects/<name>/ to that fork. For a free-tier personal GitHub account, a fork of a public repo cannot be private — GitHub blocks the in-place visibility flip with the message "For security reasons, you cannot change the visibility of a fork."

Result: any adopter on the most common shape (single person, GitHub Free, at least one private project) silently publishes their portfolio names + handover findings the moment they push to their fork. The docs don't mention this trip-wire.

This was discovered by a real adopter on 2026-05-02 after committing a bulk-handover of 11 private projects to their fork's public main. Recovery required a force-push history rewrite, redacting issue/PR bodies, deleting a backup branch, and re-architecting to a split-portfolio model. None of which is in the docs today.

Proposal — split-portfolio mode (opt-in)

Introduce a second supported pattern alongside the existing single-fork model:

~/ops/
├── apexyard/         ← public fork of me2resh/apexyard (framework code + tooling)
└── portfolio/        ← private repo (registry + per-project docs — never public)

The fork stays slim, public, upstream-aligned. The portfolio repo holds:

• apexyard.projects.yaml — registry
• projects/<name>/ — handover assessments, threat-model reports, launch-check outputs, debug reports, architecture diagrams, READMEs

Skills resolve both via a new portfolio: config block in onboarding.yaml:

portfolio:
  registry: ../portfolio/apexyard.projects.yaml         # default: ./apexyard.projects.yaml (single-fork model preserved)
  projects_dir: ../portfolio/projects                    # default: ./projects
  ideas_backlog: ../portfolio/projects/ideas-backlog.md  # default: ./projects/ideas-backlog.md

Default values preserve backward compatibility — adopters who don't set portfolio: continue with the single-fork pattern (registry + projects/ in the fork itself).

Acceptance Criteria

• onboarding.yaml schema gains an optional portfolio: block with registry, projects_dir, ideas_backlog fields. Defaults preserve today's single-fork behavior.
• Every skill that reads the registry honors the configured paths. Affected (audit list — pin in PR description):
  • /projects, /inbox, /status, /tasks, /stakeholder-update
  • /handover (writes to configured projects_dir + appends to configured registry)
  • /idea (appends to configured ideas_backlog)
  • /roadmap (reads <projects_dir>/<name>/roadmap.md)
  • /c4 (writes diagrams under configured projects_dir)
  • /validate-idea
• docs/multi-project.md documents both patterns side-by-side, with a clear "which one is right for me?" decision section that names the trip-wire (private projects + free GitHub account → use split mode).
• /setup skill asks at first run: "Do you have any private projects to manage? → recommends split mode and walks through both repo creations."
• Optional follow-up: /split-portfolio migration helper for adopters who already started with the single-fork model and need to move to split (history rewrite + force-push + new private repo + symlinks). Captures the end-to-end recovery flow that would have helped the 2026-05-02 adopter.
• Reference implementation: atlas-apex/apexyard (public fork) + atlas-apex/ops (private portfolio) demonstrate the split mode working today via symlinks + a manual .gitignore on the fork. The framework changes above formalize this.

Out of Scope

• Native private-fork support — that's a GitHub Pro / Team / Enterprise feature, outside the framework's control.
• Cross-machine portfolio sync — adopters with the split mode keep both repos in their account; a clone of each on a new machine restores the setup. Anything fancier (e.g. Dropbox-style sync of just the portfolio dir) is the adopter's concern.
• Migrating committed Issue/PR records — GitHub Issue / PR bodies survive force-pushes; once a private name has been in a public PR, redacting only hides it from casual view (the edit-history timeline is still readable via API). The /split-portfolio helper should warn about this explicitly.

Risks / Dependencies

• Skill audit — every skill currently hardcodes the registry path. Migrating each one is mechanical but must be done atomically (a half-migration leaves some skills reading the wrong path). Suggest landing as one PR.
• Backwards compatibility — existing adopters on the single-fork model must be unaffected. Defaults of the portfolio: block must point at today's locations.
• Upgrade flow — /update (upstream sync) needs to handle the case where the fork has projects/ symlinked to a different repo. The projects/README.md upstream stub may conflict with adopters who symlinked projects/ away. Document the expected resolution: adopter accepts upstream's README or keeps the symlink.

Glossary