docs: add CLAUDE.md guide + vendored manifest tracking

[jackgranatowski]

Summary

Adds comprehensive developer documentation (CLAUDE.md) explaining the plugin architecture, vendored file management, and sync workflow. Also implements automatic .vendored-manifest.json generation in the sync script to help developers and AI tools identify which files are framework-sourced and must not be edited locally.

Type

• docs
• chore / tooling

Changes

CLAUDE.md (new)

• Repo structure overview with directory annotations
• Clear warning about vendored files in admin-app/src/
• Table mapping "what you want to change" → "where to edit"
• List of safe-to-edit plugin-specific files
• Sync and framework update workflows
• Key npm scripts reference

sync-core.mjs (modified)

• Added trackVendored() to record each synced file's origin
• Added writeManifest() to generate .vendored-manifest.json after sync
• Calls trackVendored() in both local and GitHub sync paths
• Calls writeManifest() at end of both sync modes
• Manifest includes metadata (description, framework repo URL, sync timestamp) and sorted file list

Rationale

The plugin maintains a complex vendoring relationship with the SLASHED framework configurator. Developers and AI tools need clear guidance on:

1. Which files are auto-generated and will be overwritten
2. Where to make changes for different concerns
3. How the sync process works

The manifest provides machine-readable proof of vendoring, enabling tooling (linters, IDE plugins, AI assistants) to warn before editing framework-sourced files.

Checklist

• Conventional Commit messages
• No runtime behavior changes (docs + tooling only)
• Generated manifest is informational, not consumed by build
• CLAUDE.md reflects current repo structure and workflows

Notes

The .vendored-manifest.json is generated on every sync and should be committed to help reviewers and tools understand the codebase state. It serves as a "source of truth" for which files originated from the framework.

https://claude.ai/code/session_0124dAf4BHiKD1uESapMZdnK

[coderabbitai]

Warning

Review limit reached

@jackgranatowski, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fe93aa3a-b87b-41f2-a4c1-22a8667b5e35

📥 Commits

Reviewing files that changed from the base of the PR and between 9e122f7 and c88bd04.

📒 Files selected for processing (5)

• CLAUDE.md
• SLASHED-for-WP/admin-app/.vendored-manifest.json
• SLASHED-for-WP/admin-app/framework-css/badges/slashed.full.css
• SLASHED-for-WP/admin-app/scripts/sync-core.mjs
• SLASHED-for-WP/admin-app/src/lib/persistence.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/configurator-sync-framework-plugins-56vzb3

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[qodo-code-review]

PR Summary by Qodo

docs: add CLAUDE.md guide and generate vendored manifest on sync

📝 Documentation ✨ Enhancement 🕐 20-40 Minutes

AI Description

• Add CLAUDE.md to document vendoring rules, safe-to-edit areas, and sync/update workflows.
• Emit a machine-readable .vendored-manifest.json after every sync (local or GitHub).
• Record per-file framework origins to help reviewers/tools avoid editing overwritten files.

Diagram

graph TD
  Dev["Developer / CI"] --> Sync["sync-core.mjs"] --> Src["admin-app/src (vendored)"] --> Manifest[".vendored-manifest.json"]
  Sync --> Framework["SLASHED configurator/src"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Mark vendored paths via .gitattributes / CODEOWNERS

• ➕ No new generated file to commit
• ➕ GitHub UI and some tooling can surface ownership/generated status
• ➖ Doesn't provide per-file origin metadata (source repo/path/ref)
• ➖ Harder for external tools/agents to consume as ground truth

2. Vendor configurator via git subtree/submodule

• ➕ Explicit linkage to upstream history; clearer provenance
• ➕ Avoids bespoke copy logic for src/
• ➖ Heavier workflow for contributors and CI
• ➖ Doesn’t automatically solve "don’t edit here" ergonomics unless paired with additional tooling

Recommendation: The chosen approach (generate a sorted, machine-readable manifest during the existing sync step) is the best low-friction option for this repo: it preserves the current vendoring workflow while making provenance explicit for both humans and automated tools. The alternatives can complement this later (e.g., add .gitattributes hints), but they don’t replace the value of per-file origin tracking.

Files changed (2) +123 / -0

Enhancement (1) +31 / -0

sync-core.mjsTrack vendored file origins and write .vendored-manifest.json after sync +31/-0

Track vendored file origins and write .vendored-manifest.json after sync

• Adds in-memory tracking of each synced 'src/' file with a source label (local path or GitHub path/ref). Writes 'admin-app/.vendored-manifest.json' at the end of both local and remote sync modes with metadata and a sorted file list.

SLASHED-for-WP/admin-app/scripts/sync-core.mjs

Documentation (1) +92 / -0

CLAUDE.mdAdd AI/dev guide covering vendoring and sync workflows +92/-0

Add AI/dev guide covering vendoring and sync workflows

• Introduces a repository guide explaining the plugin/framework relationship, which directories are vendored, and where changes should be made. Documents the new '.vendored-manifest.json', lists safe-to-edit files, and provides key npm script references.

CLAUDE.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Absolute paths in manifest ✓ Resolved 🐞 Bug ⛨ Security

Description

In local sync mode, main() calls writeManifest(local:${local}), and writeManifest()
serializes that string into _info.source, embedding a developer’s absolute checkout path into
.vendored-manifest.json. If the manifest is committed as intended, this leaks local filesystem
details and creates noisy diffs across machines.

Code

SLASHED-for-WP/admin-app/scripts/sync-core.mjs[321]

+    writeManifest(`local:${local}`);

Relevance

⭐⭐⭐ High

Team has accepted security/privacy hardening changes before; likely to avoid leaking local paths in
committed artifacts.

PR-#19
PR-#81
PR-#27

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

writeManifest() writes _info.source directly from its argument, and local sync mode passes
local:${local} where local is a resolved local filesystem path.

SLASHED-for-WP/admin-app/scripts/sync-core.mjs[44-56]
SLASHED-for-WP/admin-app/scripts/sync-core.mjs[288-323]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Local sync writes an absolute path into `.vendored-manifest.json` (`_info.source`), which can leak developer filesystem details and cause noisy diffs when the manifest is committed.

## Issue Context
`writeManifest()` stores `sourceLabel` verbatim in the manifest. In local mode the label is currently `local:${local}`, where `local` is resolved from either `SLASHED_CONFIGURATOR_SRC` or sibling-repo discovery.

## Fix Focus Areas
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[44-56]
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[288-323]

## Suggested fix
- Change the local-mode label to avoid embedding absolute paths, e.g.:
 - `writeManifest('local')`, or
 - `writeManifest('local:SLASHED_CONFIGURATOR_SRC')` when overridden, or
 - store a redacted/relative hint instead of the full path.
- Keep the per-file `source` values (they already don’t include the absolute path).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Path separator breaks ignore ✓ Resolved 🐞 Bug ☼ Reliability

Description

trackVendored() and isIgnored() consume rel values produced by node:path.relative(), which
are OS-specific; on Windows they contain \, so .syncignore entries using / won’t match and
manifest paths become inconsistent. This can cause sync to overwrite/delete files meant to be
preserved and makes the manifest unreliable across platforms.

Code

SLASHED-for-WP/admin-app/scripts/sync-core.mjs[R40-42]

+function trackVendored(relFromSrc, source) {
+  _vendoredFiles.push({ file: `src/${relFromSrc}`, source });
+}

Relevance

⭐⭐ Medium

No prior reviews mention Windows path normalization for sync-core/.syncignore; team’s stance
unclear.

PR-#27

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The code uses relative() to compute rel, isIgnored() does exact string compares against
.syncignore entries, and trackVendored() writes src/${rel} verbatim into the manifest list;
.syncignore contains forward-slash paths.

SLASHED-for-WP/admin-app/scripts/sync-core.mjs[40-42]
SLASHED-for-WP/admin-app/scripts/sync-core.mjs[109-121]
SLASHED-for-WP/admin-app/scripts/sync-core.mjs[161-177]
SLASHED-for-WP/admin-app/scripts/sync-core.mjs[223-243]
SLASHED-for-WP/admin-app/.syncignore[15-27]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Relative paths derived via `path.relative()` are platform-dependent. Because `.syncignore` entries are written with forward slashes, Windows backslash relpaths won’t match, and the new manifest will record backslash paths.

## Issue Context
- `.syncignore` is loaded as literal strings and `isIgnored()` does direct `Set` membership checks.
- `rel` is computed using `relative(...)` in both local and GitHub sync flows and is used for ignore checks and vendored tracking.

## Fix Focus Areas
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[40-42]
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[109-121]
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[161-177]
- SLASHED-for-WP/admin-app/scripts/sync-core.mjs[223-243]
- SLASHED-for-WP/admin-app/.syncignore[15-27]

## Suggested fix
- Introduce a small helper to normalize relpaths (and optionally loaded ignore entries) to POSIX separators, e.g. `toPosixRel(p) { return p.split(sep).join('/') }` (or `replaceAll('\\', '/')`).
- Apply normalization consistently:
 - before calling `isIgnored(rel)`
 - before calling `trackVendored(rel, ...)`
 - and/or normalize `.syncignore` entries once at load time.
- Ensure the manifest always records `src/...` paths with `/` separators.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Vendoring docs inconsistent ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

CLAUDE.md says admin-app/src/ is entirely vendored and any edits will be lost, but later lists
AppOverlay.svelte and plugin-main.ts as safe-to-edit and .syncignore preserves them. This
conflicting guidance can mislead contributors/automation about what will actually be overwritten by
sync.

Code

CLAUDE.md[R20-25]

+`SLASHED-for-WP/admin-app/src/` is **entirely vendored** from the SLASHED
+framework configurator (`codeslash-dev/SLASHED → configurator/src/`). It is
+overwritten on every `npm run sync` (which also runs automatically as `predev`
+and `prebuild`).
+
+**Any edit you make directly in `admin-app/src/` will be lost on the next sync.**

Relevance

⭐⭐ Medium

No historical evidence on internal docs consistency; CLAUDE.md is new in this PR.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide claims src/ is entirely vendored and edits will be lost, but elsewhere in the same doc it
lists safe-to-edit files inside src/, and .syncignore explicitly preserves those paths.

CLAUDE.md[20-26]
CLAUDE.md[46-57]
SLASHED-for-WP/admin-app/.syncignore[21-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new guide states `admin-app/src/` is "entirely vendored" and "any edit ... will be lost", but later identifies exceptions that are intentionally preserved via `.syncignore`.

## Issue Context
This contradiction can confuse developers and AI tooling using the document to decide where edits are safe.

## Fix Focus Areas
- CLAUDE.md[18-37]
- CLAUDE.md[46-57]

## Suggested fix
- Reword to: "`admin-app/src/` is vendored *except for files protected by `.syncignore` (e.g. `plugin-main.ts`, `AppOverlay.svelte`)*".
- Optionally clarify that the manifest lists files that were *actually synced* and may exclude `.syncignore`-preserved overrides.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---