Two strategic direction changes from the CEO rolled into one PR
because they're deeply coupled — removing single-project mode
changes the install flow, and the fork-first install changes
every doc that talked about cloning into .apexstack/.

1. Drop single-project mode entirely
---------------------------------------
Single-project mode was a dual-mode compromise that added
complexity without matching how apexstack is actually used.
The audit found every skill had a mode branch that was never
exercised in practice. Users who thought they only had one repo
almost always ended up with two within a few months.

- onboarding.yaml: removed the apexstack.mode field + the
  multi-paragraph mode explainer
- apexstack.projects.yaml.example: rewritten header comment to
  lead with "no single-project fallback mode; register your one
  repo and the skills work the same"
- CLAUDE.md: OPERATING MODE section replaced with PORTFOLIO MODEL
  section explaining the fork-as-ops-repo mental model. SETUP
  section dropped the "read apexstack.mode" step.
- docs/multi-project.md: full rewrite as the canonical setup
  guide. Removed the TL;DR comparison table, the "when to switch
  to single-project" section, the "migrating from single → multi"
  section, the "going back: multi → single" section, and every
  trade-off framed against single-project.
- 8 skill files (handover, idea, inbox, projects, roadmap,
  stakeholder-update, status, tasks): dropped every mode detection
  block (grep onboarding.yaml for mode:), dropped every
  mode-comparison table, simplified scope statements to "iterates
  the registry" or equivalent. Dead code removed.
- workspace/README.md, projects/README.md: removed the "two
  modes" sections, simplified to describe the single portfolio
  pattern.
- README.md: removed the Operating modes table + the
  Single-project install (opt-out) section + the Global install
  (alternative) section (see item 2 for why the global install
  is gone).
- site/index.html: removed the "Operating modes (single &
  multi-project)" hero metric, updated the layers section lede,
  removed every single-project mention in Layer 05, removed the
  "opt-out — single-project mode" install step, removed the
  "alternative — global install" install step.

The only remaining "single-project" strings in the codebase are
TWO intentional negation disclaimers (in docs/multi-project.md
and site/index.html Layer 05) that tell anyone searching for the
concept: "there is no single-project fallback". That's a feature,
not a bug.

2. Fork-first install (replaces clone-into-.apexstack/)
--------------------------------------------------------
The old install model cloned apexstack into a hidden .apexstack/
subdirectory of a separate ops repo, then symlinked .claude/ up
one level. Three problems:

  a. Brand invisibility — .apexstack/ is a dotfile, hidden from
     ls and GitHub views. Nobody knew you were using apexstack.
  b. Two repos to maintain — your ops repo plus the nested clone.
  c. Symlink fragility — the .claude/ symlink broke on dotfile
     sync tools and Windows setups.

New model: your ops repo IS a fork of apexstack. One repo, no
nesting, no symlinks. Upgrades flow via `git fetch upstream &&
git merge upstream/main` — the standard fork workflow.

Per the CEO's call, users can rename the fork to your-org/ops
or keep it as your-org/apexstack. GitHub handles the rename
cleanly. The install docs describe the rename as optional.

- Hero install block: "git clone ... .apexstack" →
  "gh repo fork me2resh/apexstack --clone"
- Hero CTA: "★ Star on GitHub" →
  "★ Star · ⑂ Fork on GitHub" (single button, per Q3.c)
- Hero install caveat: rewrote to explain "the fork IS your ops
  repo, no nested installs, no symlinks"
- SECTION 05 / INSTALL: full rewrite. 6 steps became 5. The 5
  steps are: star+fork, add upstream remote, configure
  onboarding.yaml, create the registry, start working. The old
  "symlink runnable layer" step is gone (no symlink needed). The
  old "wire CLAUDE.md with @-import" step is gone (CLAUDE.md is
  already at the fork root).
- README.md Quick Start: same 5-step rewrite, matched to the
  site flow.
- docs/multi-project.md: complete rewrite as a setup guide
  covering the fork flow, directory layout, daily workflow,
  upgrade path (git pull upstream), trade-offs, and FAQ. ~314
  lines, honest about the pros and cons.

Side effects (positive)
-----------------------
- Layers section UX bug from the earlier screenshot is gone.
  Layer 05 no longer has "content only fills left 1/3" — added a
  new .layer--wide CSS variant with a 2-column internal grid
  (description on the left, registry file list on the right).
  Fills the full width naturally.
- Hero metric #4 changed from "2 Operating modes" to "1 Fork ·
  your ops repo in one command" — celebrates the simplification
  instead of the dropped complexity.

Not in scope
------------
- The lifecycle demo script in the hero is untouched
  (it doesn't reference install or mode)
- Role files in roles/ are untouched (no mode refs)
- Workflow files (sdlc, code-review, deployment) are untouched
  (no mode refs)
- .claude/agents/ are untouched (no mode refs)
- Hooks in .claude/hooks/ are untouched (no mode refs)
- The apexstack.mode field in the existing onboarding.yaml.example
  — this is the site's own onboarding.yaml which gets removed
  with the mode config

Verification
------------
  grep -rn "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html" --include="*.sh"
  → 2 hits, both intentional negation disclaimers

  grep -rn "mode:" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → only in docs/multi-project.md explaining why the old pattern
    was dropped (historical context paragraph)

Multi-project neutrality
------------------------
  grep -iE "flat-?mate|curios|sharp ?pick|movetwo|yumyum" \
    on all 16 changed files
  → 0 hits

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(#100): multi-project only + fork-first install

Two strategic direction changes from the CEO rolled into one PR
because they're deeply coupled — removing single-project mode
changes the install flow, and the fork-first install changes
every doc that talked about cloning into .apexstack/.

1. Drop single-project mode entirely
---------------------------------------
Single-project mode was a dual-mode compromise that added
complexity without matching how apexstack is actually used.
The audit found every skill had a mode branch that was never
exercised in practice. Users who thought they only had one repo
almost always ended up with two within a few months.

- onboarding.yaml: removed the apexstack.mode field + the
  multi-paragraph mode explainer
- apexstack.projects.yaml.example: rewritten header comment to
  lead with "no single-project fallback mode; register your one
  repo and the skills work the same"
- CLAUDE.md: OPERATING MODE section replaced with PORTFOLIO MODEL
  section explaining the fork-as-ops-repo mental model. SETUP
  section dropped the "read apexstack.mode" step.
- docs/multi-project.md: full rewrite as the canonical setup
  guide. Removed the TL;DR comparison table, the "when to switch
  to single-project" section, the "migrating from single → multi"
  section, the "going back: multi → single" section, and every
  trade-off framed against single-project.
- 8 skill files (handover, idea, inbox, projects, roadmap,
  stakeholder-update, status, tasks): dropped every mode detection
  block (grep onboarding.yaml for mode:), dropped every
  mode-comparison table, simplified scope statements to "iterates
  the registry" or equivalent. Dead code removed.
- workspace/README.md, projects/README.md: removed the "two
  modes" sections, simplified to describe the single portfolio
  pattern.
- README.md: removed the Operating modes table + the
  Single-project install (opt-out) section + the Global install
  (alternative) section (see item 2 for why the global install
  is gone).
- site/index.html: removed the "Operating modes (single &
  multi-project)" hero metric, updated the layers section lede,
  removed every single-project mention in Layer 05, removed the
  "opt-out — single-project mode" install step, removed the
  "alternative — global install" install step.

The only remaining "single-project" strings in the codebase are
TWO intentional negation disclaimers (in docs/multi-project.md
and site/index.html Layer 05) that tell anyone searching for the
concept: "there is no single-project fallback". That's a feature,
not a bug.

2. Fork-first install (replaces clone-into-.apexstack/)
--------------------------------------------------------
The old install model cloned apexstack into a hidden .apexstack/
subdirectory of a separate ops repo, then symlinked .claude/ up
one level. Three problems:

  a. Brand invisibility — .apexstack/ is a dotfile, hidden from
     ls and GitHub views. Nobody knew you were using apexstack.
  b. Two repos to maintain — your ops repo plus the nested clone.
  c. Symlink fragility — the .claude/ symlink broke on dotfile
     sync tools and Windows setups.

New model: your ops repo IS a fork of apexstack. One repo, no
nesting, no symlinks. Upgrades flow via `git fetch upstream &&
git merge upstream/main` — the standard fork workflow.

Per the CEO's call, users can rename the fork to your-org/ops
or keep it as your-org/apexstack. GitHub handles the rename
cleanly. The install docs describe the rename as optional.

- Hero install block: "git clone ... .apexstack" →
  "gh repo fork me2resh/apexstack --clone"
- Hero CTA: "★ Star on GitHub" →
  "★ Star · ⑂ Fork on GitHub" (single button, per Q3.c)
- Hero install caveat: rewrote to explain "the fork IS your ops
  repo, no nested installs, no symlinks"
- SECTION 05 / INSTALL: full rewrite. 6 steps became 5. The 5
  steps are: star+fork, add upstream remote, configure
  onboarding.yaml, create the registry, start working. The old
  "symlink runnable layer" step is gone (no symlink needed). The
  old "wire CLAUDE.md with @-import" step is gone (CLAUDE.md is
  already at the fork root).
- README.md Quick Start: same 5-step rewrite, matched to the
  site flow.
- docs/multi-project.md: complete rewrite as a setup guide
  covering the fork flow, directory layout, daily workflow,
  upgrade path (git pull upstream), trade-offs, and FAQ. ~314
  lines, honest about the pros and cons.

Side effects (positive)
-----------------------
- Layers section UX bug from the earlier screenshot is gone.
  Layer 05 no longer has "content only fills left 1/3" — added a
  new .layer--wide CSS variant with a 2-column internal grid
  (description on the left, registry file list on the right).
  Fills the full width naturally.
- Hero metric #4 changed from "2 Operating modes" to "1 Fork ·
  your ops repo in one command" — celebrates the simplification
  instead of the dropped complexity.

Not in scope
------------
- The lifecycle demo script in the hero is untouched
  (it doesn't reference install or mode)
- Role files in roles/ are untouched (no mode refs)
- Workflow files (sdlc, code-review, deployment) are untouched
  (no mode refs)
- .claude/agents/ are untouched (no mode refs)
- Hooks in .claude/hooks/ are untouched (no mode refs)
- The apexstack.mode field in the existing onboarding.yaml.example
  — this is the site's own onboarding.yaml which gets removed
  with the mode config

Verification
------------
  grep -rn "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html" --include="*.sh"
  → 2 hits, both intentional negation disclaimers

  grep -rn "mode:" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → only in docs/multi-project.md explaining why the old pattern
    was dropped (historical context paragraph)

Multi-project neutrality
------------------------
  grep -iE "flat-?mate|curios|sharp ?pick|movetwo|yumyum" \
    on all 16 changed files
  → 0 hits

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(#100): address Rex review — blockers + CTA contradiction + doc fork

Rex's delta review on a44b706 found 4 blockers + 1 site CTA
contradiction + a few vestigial mentions. Plus the deeper grep
I ran caught two more: a stale .apexstack/ example in
golden-paths/pipelines/README.md, and docs/getting-started.md
still documenting the old .apexstack/ + symlink flow.

Blockers fixed
--------------
- B1: idea/SKILL.md rule 5 "Mode-aware — detect apexstack.mode"
      → "Single backlog — every idea goes into
         projects/ideas-backlog.md"
- B2: roadmap/SKILL.md rule 6 "Mode-aware — ROADMAP.md or
      projects/<name>/roadmap.md"
      → "One roadmap per project — always write to
         projects/<name>/roadmap.md"
- B3: status/SKILL.md had a "## Multi-project mode" section and
      a "Single-project mode default:" output format header.
      Renamed to "## Portfolio output" and "## Output format
      (one-project view with --project <name>)". No behaviour
      change — just language that doesn't frame /status as
      mode-switching.

Non-blocking suggestions fixed
------------------------------
- S1 (site CTA contradiction): index.html:1732 final CTA was
      "one git clone, one symlink, and one config file away"
      → "one fork, one clone, and one config file away". The
      old line directly contradicted the "no symlinks" story.
- S3 (CLAUDE.md QUICK REFERENCE):
  - "Project registry (multi-project)" → "Portfolio registry"
  - "Per-project docs (multi-project)" → "Per-project docs"
  - "Live working copies (multi-project)" → "Live working
    copies (gitignored)"
  - "Multi-project guide" → "Full setup guide"

Also cleaned up while I was in there
------------------------------------
- inbox/SKILL.md rule 3: "Multi-project mode iterates the
  registry" → "Registry-scoped — only projects listed in
  apexstack.projects.yaml count"
- projects/SKILL.md error row: "Multi-project mode but no
  apexstack.projects.yaml" → "No apexstack.projects.yaml at
  the ops-repo root"
- projects/README.md directory layout: "ideas-backlog.md
  (multi-project mode)" → just "shared ideas backlog"

Out-of-scope but too tangled to leave
-------------------------------------
- golden-paths/pipelines/README.md: `cp` examples pointed at
  `.apexstack/golden-paths/...` as if apexstack were still a
  nested clone. Rewrote to "copy from ~/apexstack (your fork)
  to your managed project's .github/workflows/". Not strictly
  within the mode-removal scope but the README is now
  self-consistent with the fork-first install.
- docs/getting-started.md: rewrote Step 1 and Step 3 to match
  the new fork flow. Was still documenting the old .apexstack/
  + submodule + @.apexstack/CLAUDE.md @-import pattern —
  guaranteed to confuse a new adopter. Keeps parity with
  docs/multi-project.md and the site install section.

Verification
------------
  grep -rin "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 2 hits, both intentional negation disclaimers in
    docs/multi-project.md:5 and site/index.html:1367

  grep -rn "apexstack.mode\|mode: multi-project\|mode: single-project\|Mode-aware" \
    --include="*.md" --include="*.yaml" --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.html"
  → only in docs/multi-project.md historical context paragraph
    (explaining why the old pattern was dropped) and README.md
    negation disclaimer ("no .apexstack/ symlinks")

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Closes the last sub-task of the apexstack positioning epic (#100).
The Explore agent audit flagged specific gaps in both skills; these
were deferred through PRs #4-#8 because they're independent of the
positioning work. Now fixed.

/handover — 3 gaps closed
-------------------------

1. **Auto-append to the portfolio registry** (was the CRITICAL gap
   from the audit). Previously the skill printed a YAML snippet
   and told the user "add this to apexstack.projects.yaml". Users
   forgot, or miscopied, or broke the YAML indentation.

   Fix: new step 6 prompts the user `Ready to add {name} to
   apexstack.projects.yaml? (y/n)`. On y, the skill:
   - Locates the registry at the ops-repo root (creates from
     .example if missing, with a warning)
   - Appends the entry via `yq` if available, otherwise plain-text
     append with careful indentation
   - Validates the result by parsing the YAML (yq or python yaml)
   - Rolls back on failure (never leaves the registry broken)
   - Confirms the append to the user with the derived roles list

   On n, prints the snippet for manual copy-paste and continues
   without writing.

2. **Dynamic "Next Steps"** derived from the risks found. The
   old template had generic placeholders like `{first concrete
   action — usually "run /audit-deps and triage criticals"}`
   which was embarrassing to ship.

   New behaviour: a mapping table in the skill spec defines the
   derivation. Examples:
   - CVEs detected → `/audit-deps {name} — triage the {severity}
     {package} CVE before any new feature work`
   - Failing tests → `Fix the {N} failing tests in {module}
     before merging new PRs`
   - No observability → `/decide on observability ({top 2 options
     for this stack})`
   - Stale CI → `Re-enable CI — copy in golden-paths/pipelines/ci.yml`
   - Coverage unknown → `Set up test coverage reporting`
   - Backlog > 10 → `Triage the issue backlog with previous owner`
   - Missing README → `Write a minimum-viable README`

3. **Post-handover checklist** added to the assessment template,
   also dynamically tailored to the risks found. Items like "close
   {top risk} before the first feature PR", "add {name} to weekly
   /stakeholder-update rollup", "set up a coverage baseline".

Bonus gap closed: **derive the role list dynamically** from the
tech stack + CI config + security surface, instead of hard-coding
`[tech-lead, backend-engineer]`. Mapping table in the spec:
- backend deps → backend-engineer
- UI code → frontend-engineer
- CI config → platform-engineer
- deployment evidence → sre
- auth/crypto/secrets → security-auditor
- always → tech-lead

A typical handover ends up with 3-5 roles in the registry entry.

/idea — 3 gaps closed + 1 numbering bug fixed
----------------------------------------------

1. **Input validation for category**. The old step 2 asked for
   category but silently accepted anything. A user who typed
   `foo` got `Category: foo` in the backlog.

   Fix: the prompt now explicitly lists 1/2/3/4, accepts either
   the number or the word (case-insensitive), and **re-prompts
   on invalid input** with `Please pick 1-4 or type the category
   name.` Loops until valid.

   Same treatment for the description field — re-prompt if empty.

2. **Dedup check before appending** (new step 3). Prevents
   submitting the same idea twice.

   Implementation: a simple token-overlap heuristic. Normalise
   both titles (lowercase, strip punctuation), compare with a
   threshold (≥ 80% of the words in the shorter title appear in
   the longer one).

   If a match is found:

     ⚠ Similar idea already in the backlog:
       IDEA-025 — {existing title} (status: {status})

     Is this a duplicate? (y = skip, n = add anyway)

   On y: skip the append, suggest `/write-spec IDEA-025` if the
   user wants to work on the existing idea. On n: continue to
   step 4.

3. **Error handling for `gh issue create`** in step 6. Old
   behaviour: if the tracking issue creation failed, the idea
   was half-saved or the whole thing errored out. New behaviour:

     ⚠ Couldn't create the tracking issue: {reason}
       The idea is still saved in projects/ideas-backlog.md
       as IDEA-NNN.

     Try again? (y = retry, n = skip, gh = show the gh error)

   With a failure-modes table: missing auth scope, label not
   found, rate limit, network error, etc. — each has a specific
   recovery path.

   Guiding principle (now rule #8): **the backlog entry is the
   primary artefact; the tracking issue is a bonus**. Never lose
   the backlog entry because GitHub was flaky.

4. **Section numbering bug** fixed. The old file had steps 1, 2,
   4, 5, 6 — step 3 was missing because an earlier refactor
   deleted it without renumbering. With the new step 3 (dedup
   check) the sequence is now 1, 2, 3, 4, 5, 6 again.

Rules sections updated for both skills
--------------------------------------

- /handover: rule 4 is now "Auto-append to the registry (with
  confirmation)"; rule 5 is "Derive roles from the stack"; rule
  6 is "Derive next steps from the risks"; rule 10 is "Never
  break the registry".
- /idea: rule 6 is "Validate before accepting"; rule 7 is
  "Dedup before appending"; rule 8 is "The backlog is the
  primary artefact".

What's NOT in this commit
-------------------------

- The tabbed terminal animation (#102) — separate ticket,
  not part of the epic closure
- Any changes to the skill frontmatter
- Any changes to the `/handover` assessment output format
  beyond the Next Steps and Post-Handover Checklist sections
- Any changes to `/idea`'s backlog file format or ID scheme

This closes the epic #100. After this merges, apexstack is at
its v0.2 shape: positioning rewritten, lifecycle demo in the
hero, 19 roles wired in, multi-project-only + fork-first install,
and now the /handover and /idea skills that actually work
end-to-end.

Closes me2resh/apexscript-org#101
Closes me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…#9)

Closes the last sub-task of the apexstack positioning epic (#100).
The Explore agent audit flagged specific gaps in both skills; these
were deferred through PRs #4-#8 because they're independent of the
positioning work. Now fixed.

/handover — 3 gaps closed
-------------------------

1. **Auto-append to the portfolio registry** (was the CRITICAL gap
   from the audit). Previously the skill printed a YAML snippet
   and told the user "add this to apexstack.projects.yaml". Users
   forgot, or miscopied, or broke the YAML indentation.

   Fix: new step 6 prompts the user `Ready to add {name} to
   apexstack.projects.yaml? (y/n)`. On y, the skill:
   - Locates the registry at the ops-repo root (creates from
     .example if missing, with a warning)
   - Appends the entry via `yq` if available, otherwise plain-text
     append with careful indentation
   - Validates the result by parsing the YAML (yq or python yaml)
   - Rolls back on failure (never leaves the registry broken)
   - Confirms the append to the user with the derived roles list

   On n, prints the snippet for manual copy-paste and continues
   without writing.

2. **Dynamic "Next Steps"** derived from the risks found. The
   old template had generic placeholders like `{first concrete
   action — usually "run /audit-deps and triage criticals"}`
   which was embarrassing to ship.

   New behaviour: a mapping table in the skill spec defines the
   derivation. Examples:
   - CVEs detected → `/audit-deps {name} — triage the {severity}
     {package} CVE before any new feature work`
   - Failing tests → `Fix the {N} failing tests in {module}
     before merging new PRs`
   - No observability → `/decide on observability ({top 2 options
     for this stack})`
   - Stale CI → `Re-enable CI — copy in golden-paths/pipelines/ci.yml`
   - Coverage unknown → `Set up test coverage reporting`
   - Backlog > 10 → `Triage the issue backlog with previous owner`
   - Missing README → `Write a minimum-viable README`

3. **Post-handover checklist** added to the assessment template,
   also dynamically tailored to the risks found. Items like "close
   {top risk} before the first feature PR", "add {name} to weekly
   /stakeholder-update rollup", "set up a coverage baseline".

Bonus gap closed: **derive the role list dynamically** from the
tech stack + CI config + security surface, instead of hard-coding
`[tech-lead, backend-engineer]`. Mapping table in the spec:
- backend deps → backend-engineer
- UI code → frontend-engineer
- CI config → platform-engineer
- deployment evidence → sre
- auth/crypto/secrets → security-auditor
- always → tech-lead

A typical handover ends up with 3-5 roles in the registry entry.

/idea — 3 gaps closed + 1 numbering bug fixed
----------------------------------------------

1. **Input validation for category**. The old step 2 asked for
   category but silently accepted anything. A user who typed
   `foo` got `Category: foo` in the backlog.

   Fix: the prompt now explicitly lists 1/2/3/4, accepts either
   the number or the word (case-insensitive), and **re-prompts
   on invalid input** with `Please pick 1-4 or type the category
   name.` Loops until valid.

   Same treatment for the description field — re-prompt if empty.

2. **Dedup check before appending** (new step 3). Prevents
   submitting the same idea twice.

   Implementation: a simple token-overlap heuristic. Normalise
   both titles (lowercase, strip punctuation), compare with a
   threshold (≥ 80% of the words in the shorter title appear in
   the longer one).

   If a match is found:

     ⚠ Similar idea already in the backlog:
       IDEA-025 — {existing title} (status: {status})

     Is this a duplicate? (y = skip, n = add anyway)

   On y: skip the append, suggest `/write-spec IDEA-025` if the
   user wants to work on the existing idea. On n: continue to
   step 4.

3. **Error handling for `gh issue create`** in step 6. Old
   behaviour: if the tracking issue creation failed, the idea
   was half-saved or the whole thing errored out. New behaviour:

     ⚠ Couldn't create the tracking issue: {reason}
       The idea is still saved in projects/ideas-backlog.md
       as IDEA-NNN.

     Try again? (y = retry, n = skip, gh = show the gh error)

   With a failure-modes table: missing auth scope, label not
   found, rate limit, network error, etc. — each has a specific
   recovery path.

   Guiding principle (now rule #8): **the backlog entry is the
   primary artefact; the tracking issue is a bonus**. Never lose
   the backlog entry because GitHub was flaky.

4. **Section numbering bug** fixed. The old file had steps 1, 2,
   4, 5, 6 — step 3 was missing because an earlier refactor
   deleted it without renumbering. With the new step 3 (dedup
   check) the sequence is now 1, 2, 3, 4, 5, 6 again.

Rules sections updated for both skills
--------------------------------------

- /handover: rule 4 is now "Auto-append to the registry (with
  confirmation)"; rule 5 is "Derive roles from the stack"; rule
  6 is "Derive next steps from the risks"; rule 10 is "Never
  break the registry".
- /idea: rule 6 is "Validate before accepting"; rule 7 is
  "Dedup before appending"; rule 8 is "The backlog is the
  primary artefact".

What's NOT in this commit
-------------------------

- The tabbed terminal animation (#102) — separate ticket,
  not part of the epic closure
- Any changes to the skill frontmatter
- Any changes to the `/handover` assessment output format
  beyond the Next Steps and Post-Handover Checklist sections
- Any changes to `/idea`'s backlog file format or ID scheme

This closes the epic #100. After this merges, apexstack is at
its v0.2 shape: positioning rewritten, lifecycle demo in the
hero, 19 roles wired in, multi-project-only + fork-first install,
and now the /handover and /idea skills that actually work
end-to-end.

Closes me2resh/apexscript-org#101
Closes me2resh/apexscript-org#100

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…GES REQUESTED

Rex's review of #344 surfaced a real correctness gap between AgDR-0049's
Decision #4 claim and what the smoke test actually enforces. The leak-scan
is a PATH-scan (catches files at framework-distinctive paths like
_lib-portfolio-paths.sh) but is NOT a CONTENT-scan (doesn't catch SKILL.md
prose mentioning /handover, or _lib-audit-history.sh calling
portfolio_projects_dir). Several extracted files in audit-pack DO carry
such prose references.

Per the operator's chosen path (Rex's option a, honest-scope amend, not
full refactor): acknowledge the limitation in the AgDR + add a "Known
framework references" section to the audit-pack README so adopters know
what they're looking at, while preserving the generated-not-forked
contract (decision #3) that would be contradicted by content-scrubbing.

Changes:

- AgDR-0049 § Decision #4 rewritten — distinguishes path-leak guard
  (mechanically enforced) from content references (deliberate, funnel-
  pointer, graceful-degrade outside an apexyard fork). v2 may revisit if
  adopter friction surfaces.
- marketplace/audit-pack/README.md — new "Known framework references"
  section enumerates the three concrete surfaces Rex found (SKILL.md
  prose hints, _lib-audit-history.sh portfolio_projects_dir fallback,
  broken relative links to upstream docs/agdr/). Frames each as
  intentional + funnel-pointer. Flags v2 as the escape hatch.
- safety-hooks is unaffected — Rex confirmed graceful-degrades correctly.

Smoke test unchanged (path-scan is the right shape for what it catches;
the AgDR amend clarifies what it does and doesn't claim).

Refs #321

* feat(#321): scaffold marketplace/audit-pack + safety-hooks layout

- marketplace/audit-pack/ — extracted /launch-check + 8 deep-dive audit
  skills + _lib-audit-history.sh + _lib-read-config.sh + _lib-ops-root.sh
  + AI-crawler registry + 8 audit templates. Includes authored README
  and PLUGIN.json that pitch the full framework as the graduation path.
- marketplace/safety-hooks/ — extracted 7 safety hooks (secrets / main
  push / git-add-all / pre-push / commit-refs / PR-title / branch-name)
  + _lib-tracker.sh (tracker-agnostic) + _lib-read-config.sh +
  _lib-ops-root.sh + _lib-extract-pr.sh + settings.snippet.json showing
  recommended hook wiring. Same funnel-pitching README and PLUGIN.json.
- EXTRACTION_MANIFEST.json in each sub-pack records the upstream SHA
  and file inventory so the "generated, not forked" maintenance
  contract is auditable.
- Strategic intent: a one-way discovery funnel from Claude Code
  marketplace users to full-framework adopters. The two sub-packs are
  genuinely self-contained — no portfolio model, no /handover, no role
  definitions — and pitch the full framework via the README without
  pressuring.

Closes #321

* feat(#321): bin/extract-subpacks.sh + extraction smoke test

- bin/extract-subpacks.sh — idempotent extraction script that copies
  the audit-pack + safety-hooks inventories from upstream HEAD into
  marketplace/<pack>/, writes EXTRACTION_MANIFEST.json with the
  upstream SHA, and supports --dry-run + --manifest-only for CI
  validation. Invokable both locally (operator debugging) and from
  the release-tag CI workflow.
- .claude/hooks/tests/test_subpack_extraction.sh — smoke test that
  (a) runs extraction into a tmp dir, (b) asserts the file inventory
  matches the AgDR-0049 contract for both sub-packs, (c) scans for
  framework-distinctive paths that would indicate a leak
  (apexyard.projects.yaml, _lib-portfolio-paths.sh, /handover skill,
  /agdr skill, role definitions), (d) plants a deliberate leak token
  and asserts the scan catches it (proves the scan does work, not
  just exits 0 silently), and (e) verifies each sub-pack's authored
  marketplace files (PLUGIN.json, README, settings snippet) are
  present at the repo-root marketplace/.

Refs #321

* feat(#321): release-tag extraction CI workflow

- .github/workflows/extract-subpacks-on-release.yml — fires on every
  v* tag push (cut by /release) and on PRs touching extraction-
  relevant files. Runs bin/extract-subpacks.sh, then runs the
  smoke test, then uploads marketplace/ as a build artefact when
  the trigger is a release tag (90-day retention).
- The publish step (push to Claude Code marketplace) remains a
  manual operator concern in v1 — the workflow's job summary lists
  the next steps with the tag name + upstream SHA so the operator
  can take the artefact from the run and push it to the marketplace
  with the right semver.
- Per-PR mode catches contributors who break the extraction
  contract (e.g. an audit skill that adds a portfolio dependency)
  at PR time rather than at release time.

See AgDR-0049 for the rationale on release-tag-driven vs every-PR
auto-publish (the marketplace doesn't want a release per PR; every
WIP commit landing on real users is the wrong shape).

Refs #321

* docs: AgDR-0049 — marketplace sub-packs as framework funnel

Records the strategic + maintenance decisions behind the two
marketplace sub-packs (apexyard/audit-pack and apexyard/safety-hooks):

- Two-sub-pack scope vs alternatives (single mega-plugin, more
  sub-packs in v1, /rex + /migrations sub-packs)
- Generated-not-forked maintenance contract — sub-packs are
  extracted from upstream HEAD at release time, NOT separately
  maintained codebases; the framework stays single source of truth
- Release-tag-driven CI workflow + manual operator publish step
  (release-tag-only in v1; automated publish deferred to v2)
- Funnel direction is one-way (plugin → framework); the README
  pitches but does not pressure
- Performance contract — same files serve both distribution
  channels; the smoke test mechanically asserts no framework-
  distinctive elements (portfolio registry, _lib-portfolio-paths.sh,
  /handover skill, role definitions) leak into the extracted output
- Why /rex and /migrations are deferred — session-state convention
  and migration-ticket dependencies respectively don't survive
  extraction into a drop-in shape without losing the gate's value

Closes #321

* fix: shellcheck SC2064 trap-expansion + markdownlint MD051 link-fragment slugs

Two CI failures on initial #344 push:

1. shellcheck SC2064 in test_subpack_extraction.sh:34 — double-quoted
   trap expanded $TMP_ROOT at definition time rather than signal time.
   Swap inner/outer quoting (single quotes around the trap body, double
   quotes around the variable) so expansion is deferred. Cleanup now
   resolves the correct path even if TMP_ROOT is reassigned later.

2. markdownlint MD051 in both READMEs — link `#graduation-path-the-full-framework`
   doesn't match heading `## Graduation path — the full framework` because
   GFM slug-generation translates ` — ` (em-dash with spaces) to `--`
   (double dash). Swap the em-dash in the heading to a colon: the slug
   becomes `graduation-path-the-full-framework`, matching the existing
   link. Same fix in both audit-pack and safety-hooks READMEs.

Refs #321

* docs: honest-scope amend AgDR-0049 + audit-pack README per Rex's CHANGES REQUESTED

Rex's review of #344 surfaced a real correctness gap between AgDR-0049's
Decision #4 claim and what the smoke test actually enforces. The leak-scan
is a PATH-scan (catches files at framework-distinctive paths like
_lib-portfolio-paths.sh) but is NOT a CONTENT-scan (doesn't catch SKILL.md
prose mentioning /handover, or _lib-audit-history.sh calling
portfolio_projects_dir). Several extracted files in audit-pack DO carry
such prose references.

Per the operator's chosen path (Rex's option a, honest-scope amend, not
full refactor): acknowledge the limitation in the AgDR + add a "Known
framework references" section to the audit-pack README so adopters know
what they're looking at, while preserving the generated-not-forked
contract (decision #3) that would be contradicted by content-scrubbing.

Changes:

- AgDR-0049 § Decision #4 rewritten — distinguishes path-leak guard
  (mechanically enforced) from content references (deliberate, funnel-
  pointer, graceful-degrade outside an apexyard fork). v2 may revisit if
  adopter friction surfaces.
- marketplace/audit-pack/README.md — new "Known framework references"
  section enumerates the three concrete surfaces Rex found (SKILL.md
  prose hints, _lib-audit-history.sh portfolio_projects_dir fallback,
  broken relative links to upstream docs/agdr/). Frames each as
  intentional + funnel-pointer. Flags v2 as the escape hatch.
- safety-hooks is unaffected — Rex confirmed graceful-degrades correctly.

Smoke test unchanged (path-scan is the right shape for what it catches;
the AgDR amend clarifies what it does and doesn't claim).

Refs #321

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

…e2resh#4)

* docs(me2resh#100): positioning rewrite — "where projects get forged"

Reframes apexstack from "an opinionated stack for Claude Code" to
"a multi-project ops repo where projects get forged." Targets the
solo founder / technical CEO running 2-5 products and drowning in
context-switching.

Hero (site/index.html)
- Eyebrow flips from "plain markdown · zero dependencies" to
  "for founders forging multiple products"
- H1 changes from the brand name ("apexstack") to the value
  prop ("Where projects get forged.")
- New tagline: "The multi-project ops repo where your projects
  reference each other, learn from shared experience, and ship
  production-ready under a strict SDLC."
- New subhead leans into the forge framing: "You don't add
  apexstack to a project — projects get forged inside it. One
  ops repo. Every product. Shared memory. Strict gates.
  Production-ready MVPs." Addresses the Claude-Code-lock-in
  objection head-on: "Claude Code is the default driver, but
  the rules, hooks, and templates are plain markdown and shell.
  Swap the AI. Keep the forge."
- NEW hero CTA block with star-first priority:
  [★ Star on GitHub] · [or install it now ↓]
- Install command fixed from `~/.apexstack` (home dir, broken
  per the audit) to `.apexstack` (per-ops-repo, canonical)
- Caveat rewritten to match and point at both install paths

CSS
- Added .hero__cta, .cta, .cta--primary, .cta--ghost, .cta__sep
  to the existing terminal-brutalism style block. Sharp corners,
  hairline borders, no gradients. Primary CTA goes from ink → accent
  on hover. Ghost CTA is text-only with accent on hover.

Install section (site/index.html SECTION 05)
- Kept the six-step per-ops-repo walkthrough as the canonical
  path
- Kept the single-project opt-out at the bottom
- NEW "alternative — global install" step for users running
  several ops repos (founders with multiple orgs, consultants
  with multiple clients). Documents the tradeoff: symlinks
  use absolute paths, breaks if ~/.apexstack/ moves.
- Hero caveat links to #install-global for the alternative

README.md
- Hero rewritten end-to-end to match the site
- Added "Global install (alternative)" section after the
  single-project opt-out, mirroring the new site step
- gstacks.org attribution reworded to say "for teams running
  more than one product at a time"

CLAUDE.md
- Intro title changed from "AI-Native Development Stack" to
  "A Multi-Project Forge for Claude Code"
- First paragraph expanded with the forge framing and the
  explicit "projects get forged inside it, not added to it"
  phrasing, while keeping the operational instructions
  untouched so the rest of the file still drives Claude
  correctly.

Audience discovery (recorded in the epic issue)
- Primary persona: solo founder / technical CEO juggling
  2-5 products
- Tone: punchy and confident, short sentences, strong verbs
- Forge metaphor: literal
- Conversion: star first, clone second
- Objections addressed: Claude-Code lock-in (explicit),
  opinionated (leaned into — "strict gates" is the point)

NOT in this PR (tracked in the epic)
- Commands sub-page (PR 2)
- Hero shell animation (PR 3, depends on PR 2)
- Roles integration (PR 4 — the audit flagged all 19 roles
  are completely disconnected from workflows/skills/CLAUDE.md
  imports, will fix there)
- /idea and /handover skill polish (PR 5)
- AgDR backfill — explicitly skipped
- Anvil / metalwork SVG iconography — holding off on visual
  changes until the copy is locked

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(me2resh#100): fix page title, meta description, CTA separator, caveat copy

Address Rex's review on PR me2resh#4 commit b50b20e:

B1 (blocker) — Page title and meta description still said "an
opinionated stack for Claude Code" and "one drop-in stack for
Claude Code". These are the highest-leverage strings in the file
(browser tabs, search results, social cards) and they directly
contradicted the rest of the PR. Replaced with the forge framing:

  <title>ApexStack — where projects get forged</title>
  <meta description="... a multi-project ops repo where your
  projects reference each other, learn from shared experience,
  and ship production-ready under a strict SDLC. Built for
  founders running 2–5 products at once. Open source. Claude
  Code native, but plain markdown underneath.">

S2 (non-blocking) — On narrow screens where .hero__cta wraps,
the `·` separator could orphan onto its own line. Added
@media (max-width: 520px) { .cta__sep { display: none; } }
so the two CTAs stack cleanly on mobile.

S3 (non-blocking) — Hero caveat said "Five more steps in install
below" but the install section now has 6 per-ops-repo steps plus
the single-project opt-out and the new global-install alternative.
Rephrased to "Full walkthrough in install below" so the copy is
count-agnostic.

S1 (skipped) — Rex noted CLAUDE.md doesn't carry "Swap the AI.
Keep the forge." but also explicitly said the spec only required
the line in site + README, so leaving CLAUDE.md's operational
tone intact.

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(me2resh#100): revert H1 to "apexstack_" with flicker, promote forge to tagline

CEO feedback on the live site at b50b20e:
- Missed the flickering "_" cursor on the old H1 — the three-word
  H1 ("Where projects get forged.") also overflowed the hero
  width because .hero__title has white-space: nowrap; overflow:
  hidden; and was clipping at ~"projects" on a standard laptop
- Forge statement belongs in the subheading, not the H1

Changes:
- H1 reverts to "apexstack" (was "Where projects get forged.").
  The .hero__title::after pseudo-element already appends a "_"
  and animates it via the blink keyframe, so the flicker comes
  back for free.
- Tagline becomes "Where projects get forged." — the forge
  statement now sits in the visually-prominent subheading slot
  right under the H1.
- .hero__tagline font-size bumped from clamp(1rem, 1.6vw, 1.25rem)
  to clamp(1.5rem, 3vw, 2.5rem) so a 4-word punchy statement
  carries visual weight. Also font-weight 500 → 600, line-height
  1.5 → 1.25, and a small negative letter-spacing for the
  display-style treatment.
- Sub paragraph absorbs the previous tagline content merged
  with the existing subhead — one longer descriptive paragraph
  covering the multi-project promise, the forge framing, and
  the Claude-Code lock-in objection.

Typography hierarchy is now:
- H1 (huge, monospace, with blinking cursor) — brand mark
- Tagline (display-size, punchy) — the one-line promise
- Sub (body-size, descriptive) — the multi-paragraph pitch

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…sh#8)

* refactor(me2resh#100): multi-project only + fork-first install

Two strategic direction changes from the CEO rolled into one PR
because they're deeply coupled — removing single-project mode
changes the install flow, and the fork-first install changes
every doc that talked about cloning into .apexstack/.

1. Drop single-project mode entirely
---------------------------------------
Single-project mode was a dual-mode compromise that added
complexity without matching how apexstack is actually used.
The audit found every skill had a mode branch that was never
exercised in practice. Users who thought they only had one repo
almost always ended up with two within a few months.

- onboarding.yaml: removed the apexstack.mode field + the
  multi-paragraph mode explainer
- apexstack.projects.yaml.example: rewritten header comment to
  lead with "no single-project fallback mode; register your one
  repo and the skills work the same"
- CLAUDE.md: OPERATING MODE section replaced with PORTFOLIO MODEL
  section explaining the fork-as-ops-repo mental model. SETUP
  section dropped the "read apexstack.mode" step.
- docs/multi-project.md: full rewrite as the canonical setup
  guide. Removed the TL;DR comparison table, the "when to switch
  to single-project" section, the "migrating from single → multi"
  section, the "going back: multi → single" section, and every
  trade-off framed against single-project.
- 8 skill files (handover, idea, inbox, projects, roadmap,
  stakeholder-update, status, tasks): dropped every mode detection
  block (grep onboarding.yaml for mode:), dropped every
  mode-comparison table, simplified scope statements to "iterates
  the registry" or equivalent. Dead code removed.
- workspace/README.md, projects/README.md: removed the "two
  modes" sections, simplified to describe the single portfolio
  pattern.
- README.md: removed the Operating modes table + the
  Single-project install (opt-out) section + the Global install
  (alternative) section (see item 2 for why the global install
  is gone).
- site/index.html: removed the "Operating modes (single &
  multi-project)" hero metric, updated the layers section lede,
  removed every single-project mention in Layer 05, removed the
  "opt-out — single-project mode" install step, removed the
  "alternative — global install" install step.

The only remaining "single-project" strings in the codebase are
TWO intentional negation disclaimers (in docs/multi-project.md
and site/index.html Layer 05) that tell anyone searching for the
concept: "there is no single-project fallback". That's a feature,
not a bug.

2. Fork-first install (replaces clone-into-.apexstack/)
--------------------------------------------------------
The old install model cloned apexstack into a hidden .apexstack/
subdirectory of a separate ops repo, then symlinked .claude/ up
one level. Three problems:

  a. Brand invisibility — .apexstack/ is a dotfile, hidden from
     ls and GitHub views. Nobody knew you were using apexstack.
  b. Two repos to maintain — your ops repo plus the nested clone.
  c. Symlink fragility — the .claude/ symlink broke on dotfile
     sync tools and Windows setups.

New model: your ops repo IS a fork of apexstack. One repo, no
nesting, no symlinks. Upgrades flow via `git fetch upstream &&
git merge upstream/main` — the standard fork workflow.

Per the CEO's call, users can rename the fork to your-org/ops
or keep it as your-org/apexstack. GitHub handles the rename
cleanly. The install docs describe the rename as optional.

- Hero install block: "git clone ... .apexstack" →
  "gh repo fork me2resh/apexstack --clone"
- Hero CTA: "★ Star on GitHub" →
  "★ Star · ⑂ Fork on GitHub" (single button, per Q3.c)
- Hero install caveat: rewrote to explain "the fork IS your ops
  repo, no nested installs, no symlinks"
- SECTION 05 / INSTALL: full rewrite. 6 steps became 5. The 5
  steps are: star+fork, add upstream remote, configure
  onboarding.yaml, create the registry, start working. The old
  "symlink runnable layer" step is gone (no symlink needed). The
  old "wire CLAUDE.md with @-import" step is gone (CLAUDE.md is
  already at the fork root).
- README.md Quick Start: same 5-step rewrite, matched to the
  site flow.
- docs/multi-project.md: complete rewrite as a setup guide
  covering the fork flow, directory layout, daily workflow,
  upgrade path (git pull upstream), trade-offs, and FAQ. ~314
  lines, honest about the pros and cons.

Side effects (positive)
-----------------------
- Layers section UX bug from the earlier screenshot is gone.
  Layer 05 no longer has "content only fills left 1/3" — added a
  new .layer--wide CSS variant with a 2-column internal grid
  (description on the left, registry file list on the right).
  Fills the full width naturally.
- Hero metric me2resh#4 changed from "2 Operating modes" to "1 Fork ·
  your ops repo in one command" — celebrates the simplification
  instead of the dropped complexity.

Not in scope
------------
- The lifecycle demo script in the hero is untouched
  (it doesn't reference install or mode)
- Role files in roles/ are untouched (no mode refs)
- Workflow files (sdlc, code-review, deployment) are untouched
  (no mode refs)
- .claude/agents/ are untouched (no mode refs)
- Hooks in .claude/hooks/ are untouched (no mode refs)
- The apexstack.mode field in the existing onboarding.yaml.example
  — this is the site's own onboarding.yaml which gets removed
  with the mode config

Verification
------------
  grep -rn "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html" --include="*.sh"
  → 2 hits, both intentional negation disclaimers

  grep -rn "mode:" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → only in docs/multi-project.md explaining why the old pattern
    was dropped (historical context paragraph)

Multi-project neutrality
------------------------
  grep -iE "flat-?mate|curios|sharp ?pick|movetwo|yumyum" \
    on all 16 changed files
  → 0 hits

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(me2resh#100): address Rex review — blockers + CTA contradiction + doc fork

Rex's delta review on a44b706 found 4 blockers + 1 site CTA
contradiction + a few vestigial mentions. Plus the deeper grep
I ran caught two more: a stale .apexstack/ example in
golden-paths/pipelines/README.md, and docs/getting-started.md
still documenting the old .apexstack/ + symlink flow.

Blockers fixed
--------------
- B1: idea/SKILL.md rule 5 "Mode-aware — detect apexstack.mode"
      → "Single backlog — every idea goes into
         projects/ideas-backlog.md"
- B2: roadmap/SKILL.md rule 6 "Mode-aware — ROADMAP.md or
      projects/<name>/roadmap.md"
      → "One roadmap per project — always write to
         projects/<name>/roadmap.md"
- B3: status/SKILL.md had a "## Multi-project mode" section and
      a "Single-project mode default:" output format header.
      Renamed to "## Portfolio output" and "## Output format
      (one-project view with --project <name>)". No behaviour
      change — just language that doesn't frame /status as
      mode-switching.

Non-blocking suggestions fixed
------------------------------
- S1 (site CTA contradiction): index.html:1732 final CTA was
      "one git clone, one symlink, and one config file away"
      → "one fork, one clone, and one config file away". The
      old line directly contradicted the "no symlinks" story.
- S3 (CLAUDE.md QUICK REFERENCE):
  - "Project registry (multi-project)" → "Portfolio registry"
  - "Per-project docs (multi-project)" → "Per-project docs"
  - "Live working copies (multi-project)" → "Live working
    copies (gitignored)"
  - "Multi-project guide" → "Full setup guide"

Also cleaned up while I was in there
------------------------------------
- inbox/SKILL.md rule 3: "Multi-project mode iterates the
  registry" → "Registry-scoped — only projects listed in
  apexstack.projects.yaml count"
- projects/SKILL.md error row: "Multi-project mode but no
  apexstack.projects.yaml" → "No apexstack.projects.yaml at
  the ops-repo root"
- projects/README.md directory layout: "ideas-backlog.md
  (multi-project mode)" → just "shared ideas backlog"

Out-of-scope but too tangled to leave
-------------------------------------
- golden-paths/pipelines/README.md: `cp` examples pointed at
  `.apexstack/golden-paths/...` as if apexstack were still a
  nested clone. Rewrote to "copy from ~/apexstack (your fork)
  to your managed project's .github/workflows/". Not strictly
  within the mode-removal scope but the README is now
  self-consistent with the fork-first install.
- docs/getting-started.md: rewrote Step 1 and Step 3 to match
  the new fork flow. Was still documenting the old .apexstack/
  + submodule + @.apexstack/CLAUDE.md @-import pattern —
  guaranteed to confuse a new adopter. Keeps parity with
  docs/multi-project.md and the site install section.

Verification
------------
  grep -rin "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 2 hits, both intentional negation disclaimers in
    docs/multi-project.md:5 and site/index.html:1367

  grep -rn "apexstack.mode\|mode: multi-project\|mode: single-project\|Mode-aware" \
    --include="*.md" --include="*.yaml" --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.html"
  → only in docs/multi-project.md historical context paragraph
    (explaining why the old pattern was dropped) and README.md
    negation disclaimer ("no .apexstack/ symlinks")

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…d gaps) (me2resh#9)

Closes the last sub-task of the apexstack positioning epic (me2resh#100).
The Explore agent audit flagged specific gaps in both skills; these
were deferred through PRs me2resh#4-me2resh#8 because they're independent of the
positioning work. Now fixed.

/handover — 3 gaps closed
-------------------------

1. **Auto-append to the portfolio registry** (was the CRITICAL gap
   from the audit). Previously the skill printed a YAML snippet
   and told the user "add this to apexstack.projects.yaml". Users
   forgot, or miscopied, or broke the YAML indentation.

   Fix: new step 6 prompts the user `Ready to add {name} to
   apexstack.projects.yaml? (y/n)`. On y, the skill:
   - Locates the registry at the ops-repo root (creates from
     .example if missing, with a warning)
   - Appends the entry via `yq` if available, otherwise plain-text
     append with careful indentation
   - Validates the result by parsing the YAML (yq or python yaml)
   - Rolls back on failure (never leaves the registry broken)
   - Confirms the append to the user with the derived roles list

   On n, prints the snippet for manual copy-paste and continues
   without writing.

2. **Dynamic "Next Steps"** derived from the risks found. The
   old template had generic placeholders like `{first concrete
   action — usually "run /audit-deps and triage criticals"}`
   which was embarrassing to ship.

   New behaviour: a mapping table in the skill spec defines the
   derivation. Examples:
   - CVEs detected → `/audit-deps {name} — triage the {severity}
     {package} CVE before any new feature work`
   - Failing tests → `Fix the {N} failing tests in {module}
     before merging new PRs`
   - No observability → `/decide on observability ({top 2 options
     for this stack})`
   - Stale CI → `Re-enable CI — copy in golden-paths/pipelines/ci.yml`
   - Coverage unknown → `Set up test coverage reporting`
   - Backlog > 10 → `Triage the issue backlog with previous owner`
   - Missing README → `Write a minimum-viable README`

3. **Post-handover checklist** added to the assessment template,
   also dynamically tailored to the risks found. Items like "close
   {top risk} before the first feature PR", "add {name} to weekly
   /stakeholder-update rollup", "set up a coverage baseline".

Bonus gap closed: **derive the role list dynamically** from the
tech stack + CI config + security surface, instead of hard-coding
`[tech-lead, backend-engineer]`. Mapping table in the spec:
- backend deps → backend-engineer
- UI code → frontend-engineer
- CI config → platform-engineer
- deployment evidence → sre
- auth/crypto/secrets → security-auditor
- always → tech-lead

A typical handover ends up with 3-5 roles in the registry entry.

/idea — 3 gaps closed + 1 numbering bug fixed
----------------------------------------------

1. **Input validation for category**. The old step 2 asked for
   category but silently accepted anything. A user who typed
   `foo` got `Category: foo` in the backlog.

   Fix: the prompt now explicitly lists 1/2/3/4, accepts either
   the number or the word (case-insensitive), and **re-prompts
   on invalid input** with `Please pick 1-4 or type the category
   name.` Loops until valid.

   Same treatment for the description field — re-prompt if empty.

2. **Dedup check before appending** (new step 3). Prevents
   submitting the same idea twice.

   Implementation: a simple token-overlap heuristic. Normalise
   both titles (lowercase, strip punctuation), compare with a
   threshold (≥ 80% of the words in the shorter title appear in
   the longer one).

   If a match is found:

     ⚠ Similar idea already in the backlog:
       IDEA-025 — {existing title} (status: {status})

     Is this a duplicate? (y = skip, n = add anyway)

   On y: skip the append, suggest `/write-spec IDEA-025` if the
   user wants to work on the existing idea. On n: continue to
   step 4.

3. **Error handling for `gh issue create`** in step 6. Old
   behaviour: if the tracking issue creation failed, the idea
   was half-saved or the whole thing errored out. New behaviour:

     ⚠ Couldn't create the tracking issue: {reason}
       The idea is still saved in projects/ideas-backlog.md
       as IDEA-NNN.

     Try again? (y = retry, n = skip, gh = show the gh error)

   With a failure-modes table: missing auth scope, label not
   found, rate limit, network error, etc. — each has a specific
   recovery path.

   Guiding principle (now rule me2resh#8): **the backlog entry is the
   primary artefact; the tracking issue is a bonus**. Never lose
   the backlog entry because GitHub was flaky.

4. **Section numbering bug** fixed. The old file had steps 1, 2,
   4, 5, 6 — step 3 was missing because an earlier refactor
   deleted it without renumbering. With the new step 3 (dedup
   check) the sequence is now 1, 2, 3, 4, 5, 6 again.

Rules sections updated for both skills
--------------------------------------

- /handover: rule 4 is now "Auto-append to the registry (with
  confirmation)"; rule 5 is "Derive roles from the stack"; rule
  6 is "Derive next steps from the risks"; rule 10 is "Never
  break the registry".
- /idea: rule 6 is "Validate before accepting"; rule 7 is
  "Dedup before appending"; rule 8 is "The backlog is the
  primary artefact".

What's NOT in this commit
-------------------------

- The tabbed terminal animation (me2resh#102) — separate ticket,
  not part of the epic closure
- Any changes to the skill frontmatter
- Any changes to the `/handover` assessment output format
  beyond the Next Steps and Post-Handover Checklist sections
- Any changes to `/idea`'s backlog file format or ID scheme

This closes the epic me2resh#100. After this merges, apexstack is at
its v0.2 shape: positioning rewritten, lifecycle demo in the
hero, 19 roles wired in, multi-project-only + fork-first install,
and now the /handover and /idea skills that actually work
end-to-end.

Closes me2resh/apexscript-org#101
Closes me2resh/apexscript-org#100

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(#321): scaffold marketplace/audit-pack + safety-hooks layout

- marketplace/audit-pack/ — extracted /launch-check + 8 deep-dive audit
  skills + _lib-audit-history.sh + _lib-read-config.sh + _lib-ops-root.sh
  + AI-crawler registry + 8 audit templates. Includes authored README
  and PLUGIN.json that pitch the full framework as the graduation path.
- marketplace/safety-hooks/ — extracted 7 safety hooks (secrets / main
  push / git-add-all / pre-push / commit-refs / PR-title / branch-name)
  + _lib-tracker.sh (tracker-agnostic) + _lib-read-config.sh +
  _lib-ops-root.sh + _lib-extract-pr.sh + settings.snippet.json showing
  recommended hook wiring. Same funnel-pitching README and PLUGIN.json.
- EXTRACTION_MANIFEST.json in each sub-pack records the upstream SHA
  and file inventory so the "generated, not forked" maintenance
  contract is auditable.
- Strategic intent: a one-way discovery funnel from Claude Code
  marketplace users to full-framework adopters. The two sub-packs are
  genuinely self-contained — no portfolio model, no /handover, no role
  definitions — and pitch the full framework via the README without
  pressuring.

Closes #321

* feat(#321): bin/extract-subpacks.sh + extraction smoke test

- bin/extract-subpacks.sh — idempotent extraction script that copies
  the audit-pack + safety-hooks inventories from upstream HEAD into
  marketplace/<pack>/, writes EXTRACTION_MANIFEST.json with the
  upstream SHA, and supports --dry-run + --manifest-only for CI
  validation. Invokable both locally (operator debugging) and from
  the release-tag CI workflow.
- .claude/hooks/tests/test_subpack_extraction.sh — smoke test that
  (a) runs extraction into a tmp dir, (b) asserts the file inventory
  matches the AgDR-0049 contract for both sub-packs, (c) scans for
  framework-distinctive paths that would indicate a leak
  (apexyard.projects.yaml, _lib-portfolio-paths.sh, /handover skill,
  /agdr skill, role definitions), (d) plants a deliberate leak token
  and asserts the scan catches it (proves the scan does work, not
  just exits 0 silently), and (e) verifies each sub-pack's authored
  marketplace files (PLUGIN.json, README, settings snippet) are
  present at the repo-root marketplace/.

Refs #321

* feat(#321): release-tag extraction CI workflow

- .github/workflows/extract-subpacks-on-release.yml — fires on every
  v* tag push (cut by /release) and on PRs touching extraction-
  relevant files. Runs bin/extract-subpacks.sh, then runs the
  smoke test, then uploads marketplace/ as a build artefact when
  the trigger is a release tag (90-day retention).
- The publish step (push to Claude Code marketplace) remains a
  manual operator concern in v1 — the workflow's job summary lists
  the next steps with the tag name + upstream SHA so the operator
  can take the artefact from the run and push it to the marketplace
  with the right semver.
- Per-PR mode catches contributors who break the extraction
  contract (e.g. an audit skill that adds a portfolio dependency)
  at PR time rather than at release time.

See AgDR-0049 for the rationale on release-tag-driven vs every-PR
auto-publish (the marketplace doesn't want a release per PR; every
WIP commit landing on real users is the wrong shape).

Refs #321

* docs: AgDR-0049 — marketplace sub-packs as framework funnel

Records the strategic + maintenance decisions behind the two
marketplace sub-packs (apexyard/audit-pack and apexyard/safety-hooks):

- Two-sub-pack scope vs alternatives (single mega-plugin, more
  sub-packs in v1, /rex + /migrations sub-packs)
- Generated-not-forked maintenance contract — sub-packs are
  extracted from upstream HEAD at release time, NOT separately
  maintained codebases; the framework stays single source of truth
- Release-tag-driven CI workflow + manual operator publish step
  (release-tag-only in v1; automated publish deferred to v2)
- Funnel direction is one-way (plugin → framework); the README
  pitches but does not pressure
- Performance contract — same files serve both distribution
  channels; the smoke test mechanically asserts no framework-
  distinctive elements (portfolio registry, _lib-portfolio-paths.sh,
  /handover skill, role definitions) leak into the extracted output
- Why /rex and /migrations are deferred — session-state convention
  and migration-ticket dependencies respectively don't survive
  extraction into a drop-in shape without losing the gate's value

Closes #321

* fix: shellcheck SC2064 trap-expansion + markdownlint MD051 link-fragment slugs

Two CI failures on initial #344 push:

1. shellcheck SC2064 in test_subpack_extraction.sh:34 — double-quoted
   trap expanded $TMP_ROOT at definition time rather than signal time.
   Swap inner/outer quoting (single quotes around the trap body, double
   quotes around the variable) so expansion is deferred. Cleanup now
   resolves the correct path even if TMP_ROOT is reassigned later.

2. markdownlint MD051 in both READMEs — link `#graduation-path-the-full-framework`
   doesn't match heading `## Graduation path — the full framework` because
   GFM slug-generation translates ` — ` (em-dash with spaces) to `--`
   (double dash). Swap the em-dash in the heading to a colon: the slug
   becomes `graduation-path-the-full-framework`, matching the existing
   link. Same fix in both audit-pack and safety-hooks READMEs.

Refs #321

* docs: honest-scope amend AgDR-0049 + audit-pack README per Rex's CHANGES REQUESTED

Rex's review of #344 surfaced a real correctness gap between AgDR-0049's
Decision #4 claim and what the smoke test actually enforces. The leak-scan
is a PATH-scan (catches files at framework-distinctive paths like
_lib-portfolio-paths.sh) but is NOT a CONTENT-scan (doesn't catch SKILL.md
prose mentioning /handover, or _lib-audit-history.sh calling
portfolio_projects_dir). Several extracted files in audit-pack DO carry
such prose references.

Per the operator's chosen path (Rex's option a, honest-scope amend, not
full refactor): acknowledge the limitation in the AgDR + add a "Known
framework references" section to the audit-pack README so adopters know
what they're looking at, while preserving the generated-not-forked
contract (decision #3) that would be contradicted by content-scrubbing.

Changes:

- AgDR-0049 § Decision #4 rewritten — distinguishes path-leak guard
  (mechanically enforced) from content references (deliberate, funnel-
  pointer, graceful-degrade outside an apexyard fork). v2 may revisit if
  adopter friction surfaces.
- marketplace/audit-pack/README.md — new "Known framework references"
  section enumerates the three concrete surfaces Rex found (SKILL.md
  prose hints, _lib-audit-history.sh portfolio_projects_dir fallback,
  broken relative links to upstream docs/agdr/). Frames each as
  intentional + funnel-pointer. Flags v2 as the escape hatch.
- safety-hooks is unaffected — Rex confirmed graceful-degrades correctly.

Smoke test unchanged (path-scan is the right shape for what it catches;
the AgDR amend clarifies what it does and doesn't claim).

Refs #321

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

…e2resh#4)

* docs(me2resh#100): positioning rewrite — "where projects get forged"

Reframes apexstack from "an opinionated stack for Claude Code" to
"a multi-project ops repo where projects get forged." Targets the
solo founder / technical CEO running 2-5 products and drowning in
context-switching.

Hero (site/index.html)
- Eyebrow flips from "plain markdown · zero dependencies" to
  "for founders forging multiple products"
- H1 changes from the brand name ("apexstack") to the value
  prop ("Where projects get forged.")
- New tagline: "The multi-project ops repo where your projects
  reference each other, learn from shared experience, and ship
  production-ready under a strict SDLC."
- New subhead leans into the forge framing: "You don't add
  apexstack to a project — projects get forged inside it. One
  ops repo. Every product. Shared memory. Strict gates.
  Production-ready MVPs." Addresses the Claude-Code-lock-in
  objection head-on: "Claude Code is the default driver, but
  the rules, hooks, and templates are plain markdown and shell.
  Swap the AI. Keep the forge."
- NEW hero CTA block with star-first priority:
  [★ Star on GitHub] · [or install it now ↓]
- Install command fixed from `~/.apexstack` (home dir, broken
  per the audit) to `.apexstack` (per-ops-repo, canonical)
- Caveat rewritten to match and point at both install paths

CSS
- Added .hero__cta, .cta, .cta--primary, .cta--ghost, .cta__sep
  to the existing terminal-brutalism style block. Sharp corners,
  hairline borders, no gradients. Primary CTA goes from ink → accent
  on hover. Ghost CTA is text-only with accent on hover.

Install section (site/index.html SECTION 05)
- Kept the six-step per-ops-repo walkthrough as the canonical
  path
- Kept the single-project opt-out at the bottom
- NEW "alternative — global install" step for users running
  several ops repos (founders with multiple orgs, consultants
  with multiple clients). Documents the tradeoff: symlinks
  use absolute paths, breaks if ~/.apexstack/ moves.
- Hero caveat links to #install-global for the alternative

README.md
- Hero rewritten end-to-end to match the site
- Added "Global install (alternative)" section after the
  single-project opt-out, mirroring the new site step
- gstacks.org attribution reworded to say "for teams running
  more than one product at a time"

CLAUDE.md
- Intro title changed from "AI-Native Development Stack" to
  "A Multi-Project Forge for Claude Code"
- First paragraph expanded with the forge framing and the
  explicit "projects get forged inside it, not added to it"
  phrasing, while keeping the operational instructions
  untouched so the rest of the file still drives Claude
  correctly.

Audience discovery (recorded in the epic issue)
- Primary persona: solo founder / technical CEO juggling
  2-5 products
- Tone: punchy and confident, short sentences, strong verbs
- Forge metaphor: literal
- Conversion: star first, clone second
- Objections addressed: Claude-Code lock-in (explicit),
  opinionated (leaned into — "strict gates" is the point)

NOT in this PR (tracked in the epic)
- Commands sub-page (PR 2)
- Hero shell animation (PR 3, depends on PR 2)
- Roles integration (PR 4 — the audit flagged all 19 roles
  are completely disconnected from workflows/skills/CLAUDE.md
  imports, will fix there)
- /idea and /handover skill polish (PR 5)
- AgDR backfill — explicitly skipped
- Anvil / metalwork SVG iconography — holding off on visual
  changes until the copy is locked

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(me2resh#100): fix page title, meta description, CTA separator, caveat copy

Address Rex's review on PR me2resh#4 commit a044bd2:

B1 (blocker) — Page title and meta description still said "an
opinionated stack for Claude Code" and "one drop-in stack for
Claude Code". These are the highest-leverage strings in the file
(browser tabs, search results, social cards) and they directly
contradicted the rest of the PR. Replaced with the forge framing:

  <title>ApexStack — where projects get forged</title>
  <meta description="... a multi-project ops repo where your
  projects reference each other, learn from shared experience,
  and ship production-ready under a strict SDLC. Built for
  founders running 2–5 products at once. Open source. Claude
  Code native, but plain markdown underneath.">

S2 (non-blocking) — On narrow screens where .hero__cta wraps,
the `·` separator could orphan onto its own line. Added
@media (max-width: 520px) { .cta__sep { display: none; } }
so the two CTAs stack cleanly on mobile.

S3 (non-blocking) — Hero caveat said "Five more steps in install
below" but the install section now has 6 per-ops-repo steps plus
the single-project opt-out and the new global-install alternative.
Rephrased to "Full walkthrough in install below" so the copy is
count-agnostic.

S1 (skipped) — Rex noted CLAUDE.md doesn't carry "Swap the AI.
Keep the forge." but also explicitly said the spec only required
the line in site + README, so leaving CLAUDE.md's operational
tone intact.

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs(me2resh#100): revert H1 to "apexstack_" with flicker, promote forge to tagline

CEO feedback on the live site at a044bd2:
- Missed the flickering "_" cursor on the old H1 — the three-word
  H1 ("Where projects get forged.") also overflowed the hero
  width because .hero__title has white-space: nowrap; overflow:
  hidden; and was clipping at ~"projects" on a standard laptop
- Forge statement belongs in the subheading, not the H1

Changes:
- H1 reverts to "apexstack" (was "Where projects get forged.").
  The .hero__title::after pseudo-element already appends a "_"
  and animates it via the blink keyframe, so the flicker comes
  back for free.
- Tagline becomes "Where projects get forged." — the forge
  statement now sits in the visually-prominent subheading slot
  right under the H1.
- .hero__tagline font-size bumped from clamp(1rem, 1.6vw, 1.25rem)
  to clamp(1.5rem, 3vw, 2.5rem) so a 4-word punchy statement
  carries visual weight. Also font-weight 500 → 600, line-height
  1.5 → 1.25, and a small negative letter-spacing for the
  display-style treatment.
- Sub paragraph absorbs the previous tagline content merged
  with the existing subhead — one longer descriptive paragraph
  covering the multi-project promise, the forge framing, and
  the Claude-Code lock-in objection.

Typography hierarchy is now:
- H1 (huge, monospace, with blinking cursor) — brand mark
- Tagline (display-size, punchy) — the one-line promise
- Sub (body-size, descriptive) — the multi-paragraph pitch

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…sh#8)

* refactor(me2resh#100): multi-project only + fork-first install

Two strategic direction changes from the CEO rolled into one PR
because they're deeply coupled — removing single-project mode
changes the install flow, and the fork-first install changes
every doc that talked about cloning into .apexstack/.

1. Drop single-project mode entirely
---------------------------------------
Single-project mode was a dual-mode compromise that added
complexity without matching how apexstack is actually used.
The audit found every skill had a mode branch that was never
exercised in practice. Users who thought they only had one repo
almost always ended up with two within a few months.

- onboarding.yaml: removed the apexstack.mode field + the
  multi-paragraph mode explainer
- apexstack.projects.yaml.example: rewritten header comment to
  lead with "no single-project fallback mode; register your one
  repo and the skills work the same"
- CLAUDE.md: OPERATING MODE section replaced with PORTFOLIO MODEL
  section explaining the fork-as-ops-repo mental model. SETUP
  section dropped the "read apexstack.mode" step.
- docs/multi-project.md: full rewrite as the canonical setup
  guide. Removed the TL;DR comparison table, the "when to switch
  to single-project" section, the "migrating from single → multi"
  section, the "going back: multi → single" section, and every
  trade-off framed against single-project.
- 8 skill files (handover, idea, inbox, projects, roadmap,
  stakeholder-update, status, tasks): dropped every mode detection
  block (grep onboarding.yaml for mode:), dropped every
  mode-comparison table, simplified scope statements to "iterates
  the registry" or equivalent. Dead code removed.
- workspace/README.md, projects/README.md: removed the "two
  modes" sections, simplified to describe the single portfolio
  pattern.
- README.md: removed the Operating modes table + the
  Single-project install (opt-out) section + the Global install
  (alternative) section (see item 2 for why the global install
  is gone).
- site/index.html: removed the "Operating modes (single &
  multi-project)" hero metric, updated the layers section lede,
  removed every single-project mention in Layer 05, removed the
  "opt-out — single-project mode" install step, removed the
  "alternative — global install" install step.

The only remaining "single-project" strings in the codebase are
TWO intentional negation disclaimers (in docs/multi-project.md
and site/index.html Layer 05) that tell anyone searching for the
concept: "there is no single-project fallback". That's a feature,
not a bug.

2. Fork-first install (replaces clone-into-.apexstack/)
--------------------------------------------------------
The old install model cloned apexstack into a hidden .apexstack/
subdirectory of a separate ops repo, then symlinked .claude/ up
one level. Three problems:

  a. Brand invisibility — .apexstack/ is a dotfile, hidden from
     ls and GitHub views. Nobody knew you were using apexstack.
  b. Two repos to maintain — your ops repo plus the nested clone.
  c. Symlink fragility — the .claude/ symlink broke on dotfile
     sync tools and Windows setups.

New model: your ops repo IS a fork of apexstack. One repo, no
nesting, no symlinks. Upgrades flow via `git fetch upstream &&
git merge upstream/main` — the standard fork workflow.

Per the CEO's call, users can rename the fork to your-org/ops
or keep it as your-org/apexstack. GitHub handles the rename
cleanly. The install docs describe the rename as optional.

- Hero install block: "git clone ... .apexstack" →
  "gh repo fork me2resh/apexstack --clone"
- Hero CTA: "★ Star on GitHub" →
  "★ Star · ⑂ Fork on GitHub" (single button, per Q3.c)
- Hero install caveat: rewrote to explain "the fork IS your ops
  repo, no nested installs, no symlinks"
- SECTION 05 / INSTALL: full rewrite. 6 steps became 5. The 5
  steps are: star+fork, add upstream remote, configure
  onboarding.yaml, create the registry, start working. The old
  "symlink runnable layer" step is gone (no symlink needed). The
  old "wire CLAUDE.md with @-import" step is gone (CLAUDE.md is
  already at the fork root).
- README.md Quick Start: same 5-step rewrite, matched to the
  site flow.
- docs/multi-project.md: complete rewrite as a setup guide
  covering the fork flow, directory layout, daily workflow,
  upgrade path (git pull upstream), trade-offs, and FAQ. ~314
  lines, honest about the pros and cons.

Side effects (positive)
-----------------------
- Layers section UX bug from the earlier screenshot is gone.
  Layer 05 no longer has "content only fills left 1/3" — added a
  new .layer--wide CSS variant with a 2-column internal grid
  (description on the left, registry file list on the right).
  Fills the full width naturally.
- Hero metric me2resh#4 changed from "2 Operating modes" to "1 Fork ·
  your ops repo in one command" — celebrates the simplification
  instead of the dropped complexity.

Not in scope
------------
- The lifecycle demo script in the hero is untouched
  (it doesn't reference install or mode)
- Role files in roles/ are untouched (no mode refs)
- Workflow files (sdlc, code-review, deployment) are untouched
  (no mode refs)
- .claude/agents/ are untouched (no mode refs)
- Hooks in .claude/hooks/ are untouched (no mode refs)
- The apexstack.mode field in the existing onboarding.yaml.example
  — this is the site's own onboarding.yaml which gets removed
  with the mode config

Verification
------------
  grep -rn "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html" --include="*.sh"
  → 2 hits, both intentional negation disclaimers

  grep -rn "mode:" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → only in docs/multi-project.md explaining why the old pattern
    was dropped (historical context paragraph)

Multi-project neutrality
------------------------
  grep -iE "flat-?mate|curios|sharp ?pick|movetwo|yumyum" \
    on all 16 changed files
  → 0 hits

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(me2resh#100): address Rex review — blockers + CTA contradiction + doc fork

Rex's delta review on 160148f found 4 blockers + 1 site CTA
contradiction + a few vestigial mentions. Plus the deeper grep
I ran caught two more: a stale .apexstack/ example in
golden-paths/pipelines/README.md, and docs/getting-started.md
still documenting the old .apexstack/ + symlink flow.

Blockers fixed
--------------
- B1: idea/SKILL.md rule 5 "Mode-aware — detect apexstack.mode"
      → "Single backlog — every idea goes into
         projects/ideas-backlog.md"
- B2: roadmap/SKILL.md rule 6 "Mode-aware — ROADMAP.md or
      projects/<name>/roadmap.md"
      → "One roadmap per project — always write to
         projects/<name>/roadmap.md"
- B3: status/SKILL.md had a "## Multi-project mode" section and
      a "Single-project mode default:" output format header.
      Renamed to "## Portfolio output" and "## Output format
      (one-project view with --project <name>)". No behaviour
      change — just language that doesn't frame /status as
      mode-switching.

Non-blocking suggestions fixed
------------------------------
- S1 (site CTA contradiction): index.html:1732 final CTA was
      "one git clone, one symlink, and one config file away"
      → "one fork, one clone, and one config file away". The
      old line directly contradicted the "no symlinks" story.
- S3 (CLAUDE.md QUICK REFERENCE):
  - "Project registry (multi-project)" → "Portfolio registry"
  - "Per-project docs (multi-project)" → "Per-project docs"
  - "Live working copies (multi-project)" → "Live working
    copies (gitignored)"
  - "Multi-project guide" → "Full setup guide"

Also cleaned up while I was in there
------------------------------------
- inbox/SKILL.md rule 3: "Multi-project mode iterates the
  registry" → "Registry-scoped — only projects listed in
  apexstack.projects.yaml count"
- projects/SKILL.md error row: "Multi-project mode but no
  apexstack.projects.yaml" → "No apexstack.projects.yaml at
  the ops-repo root"
- projects/README.md directory layout: "ideas-backlog.md
  (multi-project mode)" → just "shared ideas backlog"

Out-of-scope but too tangled to leave
-------------------------------------
- golden-paths/pipelines/README.md: `cp` examples pointed at
  `.apexstack/golden-paths/...` as if apexstack were still a
  nested clone. Rewrote to "copy from ~/apexstack (your fork)
  to your managed project's .github/workflows/". Not strictly
  within the mode-removal scope but the README is now
  self-consistent with the fork-first install.
- docs/getting-started.md: rewrote Step 1 and Step 3 to match
  the new fork flow. Was still documenting the old .apexstack/
  + submodule + @.apexstack/CLAUDE.md @-import pattern —
  guaranteed to confuse a new adopter. Keeps parity with
  docs/multi-project.md and the site install section.

Verification
------------
  grep -rin "single-project" --include="*.md" --include="*.yaml" \
    --include="*.html"
  → 2 hits, both intentional negation disclaimers in
    docs/multi-project.md:5 and site/index.html:1367

  grep -rn "apexstack.mode\|mode: multi-project\|mode: single-project\|Mode-aware" \
    --include="*.md" --include="*.yaml" --include="*.html"
  → 0 hits

  grep -rn "\.apexstack/" --include="*.md" --include="*.html"
  → only in docs/multi-project.md historical context paragraph
    (explaining why the old pattern was dropped) and README.md
    negation disclaimer ("no .apexstack/ symlinks")

Refs me2resh/apexscript-org#100

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…d gaps) (me2resh#9)

Closes the last sub-task of the apexstack positioning epic (me2resh#100).
The Explore agent audit flagged specific gaps in both skills; these
were deferred through PRs me2resh#4-me2resh#8 because they're independent of the
positioning work. Now fixed.

/handover — 3 gaps closed
-------------------------

1. **Auto-append to the portfolio registry** (was the CRITICAL gap
   from the audit). Previously the skill printed a YAML snippet
   and told the user "add this to apexstack.projects.yaml". Users
   forgot, or miscopied, or broke the YAML indentation.

   Fix: new step 6 prompts the user `Ready to add {name} to
   apexstack.projects.yaml? (y/n)`. On y, the skill:
   - Locates the registry at the ops-repo root (creates from
     .example if missing, with a warning)
   - Appends the entry via `yq` if available, otherwise plain-text
     append with careful indentation
   - Validates the result by parsing the YAML (yq or python yaml)
   - Rolls back on failure (never leaves the registry broken)
   - Confirms the append to the user with the derived roles list

   On n, prints the snippet for manual copy-paste and continues
   without writing.

2. **Dynamic "Next Steps"** derived from the risks found. The
   old template had generic placeholders like `{first concrete
   action — usually "run /audit-deps and triage criticals"}`
   which was embarrassing to ship.

   New behaviour: a mapping table in the skill spec defines the
   derivation. Examples:
   - CVEs detected → `/audit-deps {name} — triage the {severity}
     {package} CVE before any new feature work`
   - Failing tests → `Fix the {N} failing tests in {module}
     before merging new PRs`
   - No observability → `/decide on observability ({top 2 options
     for this stack})`
   - Stale CI → `Re-enable CI — copy in golden-paths/pipelines/ci.yml`
   - Coverage unknown → `Set up test coverage reporting`
   - Backlog > 10 → `Triage the issue backlog with previous owner`
   - Missing README → `Write a minimum-viable README`

3. **Post-handover checklist** added to the assessment template,
   also dynamically tailored to the risks found. Items like "close
   {top risk} before the first feature PR", "add {name} to weekly
   /stakeholder-update rollup", "set up a coverage baseline".

Bonus gap closed: **derive the role list dynamically** from the
tech stack + CI config + security surface, instead of hard-coding
`[tech-lead, backend-engineer]`. Mapping table in the spec:
- backend deps → backend-engineer
- UI code → frontend-engineer
- CI config → platform-engineer
- deployment evidence → sre
- auth/crypto/secrets → security-auditor
- always → tech-lead

A typical handover ends up with 3-5 roles in the registry entry.

/idea — 3 gaps closed + 1 numbering bug fixed
----------------------------------------------

1. **Input validation for category**. The old step 2 asked for
   category but silently accepted anything. A user who typed
   `foo` got `Category: foo` in the backlog.

   Fix: the prompt now explicitly lists 1/2/3/4, accepts either
   the number or the word (case-insensitive), and **re-prompts
   on invalid input** with `Please pick 1-4 or type the category
   name.` Loops until valid.

   Same treatment for the description field — re-prompt if empty.

2. **Dedup check before appending** (new step 3). Prevents
   submitting the same idea twice.

   Implementation: a simple token-overlap heuristic. Normalise
   both titles (lowercase, strip punctuation), compare with a
   threshold (≥ 80% of the words in the shorter title appear in
   the longer one).

   If a match is found:

     ⚠ Similar idea already in the backlog:
       IDEA-025 — {existing title} (status: {status})

     Is this a duplicate? (y = skip, n = add anyway)

   On y: skip the append, suggest `/write-spec IDEA-025` if the
   user wants to work on the existing idea. On n: continue to
   step 4.

3. **Error handling for `gh issue create`** in step 6. Old
   behaviour: if the tracking issue creation failed, the idea
   was half-saved or the whole thing errored out. New behaviour:

     ⚠ Couldn't create the tracking issue: {reason}
       The idea is still saved in projects/ideas-backlog.md
       as IDEA-NNN.

     Try again? (y = retry, n = skip, gh = show the gh error)

   With a failure-modes table: missing auth scope, label not
   found, rate limit, network error, etc. — each has a specific
   recovery path.

   Guiding principle (now rule me2resh#8): **the backlog entry is the
   primary artefact; the tracking issue is a bonus**. Never lose
   the backlog entry because GitHub was flaky.

4. **Section numbering bug** fixed. The old file had steps 1, 2,
   4, 5, 6 — step 3 was missing because an earlier refactor
   deleted it without renumbering. With the new step 3 (dedup
   check) the sequence is now 1, 2, 3, 4, 5, 6 again.

Rules sections updated for both skills
--------------------------------------

- /handover: rule 4 is now "Auto-append to the registry (with
  confirmation)"; rule 5 is "Derive roles from the stack"; rule
  6 is "Derive next steps from the risks"; rule 10 is "Never
  break the registry".
- /idea: rule 6 is "Validate before accepting"; rule 7 is
  "Dedup before appending"; rule 8 is "The backlog is the
  primary artefact".

What's NOT in this commit
-------------------------

- The tabbed terminal animation (me2resh#102) — separate ticket,
  not part of the epic closure
- Any changes to the skill frontmatter
- Any changes to the `/handover` assessment output format
  beyond the Next Steps and Post-Handover Checklist sections
- Any changes to `/idea`'s backlog file format or ID scheme

This closes the epic me2resh#100. After this merges, apexstack is at
its v0.2 shape: positioning rewritten, lifecycle demo in the
hero, 19 roles wired in, multi-project-only + fork-first install,
and now the /handover and /idea skills that actually work
end-to-end.

Closes me2resh/apexscript-org#101
Closes me2resh/apexscript-org#100

Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>