Repo polish: README, architecture diagram, verified quickstart

[dr-gareth-roberts]

Summary

Interview-safety polish pass. Small, focused diff (4 files) — no architecture changes, no major version bumps, no feature churn.

• Mermaid architecture diagram — replaced the ASCII pipeline sketch with a native-rendering mermaid flowchart (10 nodes) showing the core score → place → pack → quality gate → trace pipeline plus the adaptive-weights, cache-topology, and drift/immune/council subsystems that feed and observe it.
• TS ↔ Python clarity — added a table to the Python section mapping the three code locations: packages/ (TypeScript reference workspace), python/context_engineering/ (1:1 published port), python/context_framework/ (applied domain runtimes).
• Security: two high-severity Dependabot alerts cleared — bumped http-proxy-middleware ^4.0.0 → ^4.1.1 (resolves 4.2.0, fixes multipart CRLF injection + host-routing bypass) and added a pnpm override form-data: ">=4.0.6" (resolves 4.0.6, fixes CRLF injection via unescaped multipart field names).
• Removed leaked artifact — deleted the stray root claude symlink pointing at /Users/k/.local/bin/claude (a broken, personal-machine path).

What was verified (in-sandbox)

Fresh pnpm install + pnpm build:packages, then Python pip install -e ".[dev]". All quickstart paths run with no API keys:

# README top TS snippet (pack primitive)
$ npx tsx qs.ts
selected: [ 'system', 'query', 'docs', 'history' ]
dropped: []

# examples/node-basic/index.mjs
$ node examples/node-basic/index.mjs
... totalTokens: 22, stats: { remainingTokens: 2, selectedCount: 2, droppedCount: 1 }
Provider ready yes

# examples/rag-chatbot (README-featured, no keys)
$ npx tsx examples/rag-chatbot/index.ts
... Scenario 1/2 pack + allocation + quality gate tables render; exits 0

# README Python snippet
$ python -c "from context_engineering import pack, ContextItem, Budget; ..."
selected: ['system', 'query']
dropped: []

# examples/python-basic/example.py
$ python examples/python-basic/example.py
Pack result {... 'selectedCount': 2, 'droppedCount': 1}

Also confirmed: ce-core tests 495/495 green, pnpm build:app succeeds after the dependency bump, and npx prettier --check . passes repo-wide.

Remaining gaps (not addressed here)

• Low-severity esbuild <0.28.1 alert (Windows-only dev-server file read) — Dependabot PR chore(deps-dev): Bump esbuild from 0.27.7 to 0.28.1 #55 already open; left out to keep this diff to the two high-severity packages in scope.
• Dependabot PR backlog (chore(deps-dev): Bump esbuild from 0.27.7 to 0.28.1 #55, chore(deps): Bump pnpm/action-setup from 6.0.8 to 6.0.9 #56, chore(deps): Bump http-proxy-middleware from 4.0.0 to 4.1.1 #59, chore(deps): Bump actions/checkout from 6.0.3 to 7.0.0 #60, chore(deps): Bump actions/setup-python from 6.2.0 to 6.3.0 #62, chore(deps): Bump the production-dependencies group across 1 directory with 8 updates #63, chore(deps-dev): Bump the dev-dependencies group across 1 directory with 19 updates #65). Note: the grouped production-deps PR "chore(deps): Bump the production-dependencies group across 1 directory with 7 updates #61" referenced during triage is now closed; chore(deps): Bump the production-dependencies group across 1 directory with 8 updates #63 is the current open group.
• Placeholder author email gareth@zmail.com in package.json; stale localhost:5173 note in CLAUDE.md (README is correct at :3000); pointless root .gitkeep.

Full detail in the polish-pack gaps.md.

🤖 Generated with Claude Code

Summary by Sourcery

Polish repository docs and dependencies while tightening security posture and removing a stray artifact.

New Features:

• Document the core score → place → pack → quality gate → trace pipeline with a Mermaid architecture diagram and supporting explanation in the README.
• Clarify the relationship between TypeScript and Python code by adding a table mapping the TS workspace, Python port, and applied Python runtimes in the README.

Bug Fixes:

• Address high‑severity security alerts by bumping http-proxy-middleware and enforcing a minimum form-data version via pnpm overrides.
• Remove an accidental root-level symlink artifact from the repository.

Build:

• Update package.json dependency constraints and pnpm override configuration to align with the new, secure versions.

[sourcery-ai]

Reviewer's Guide

Documentation polish plus security dependency updates and removal of a stray local artifact. No core algorithm or architecture changes.

Flow diagram for ce-core score→place→pack→quality gate→trace pipeline

flowchart LR
    IN([Items + Budget]) --> SCORE[Score]
    SCORE --> PLACE[Place]
    PLACE --> PACK[Pack]
    PACK --> GATE{Quality Gate}
    GATE --> TRACE([Trace])

    ADAPT[Adaptive weights] -. learned .-> SCORE
    CACHE[Cache topology] -. ordering .-> PLACE
    MEM[(Memory / Providers)] --> IN
    GATE -. monitor .-> WATCH[Drift · Immune · Council]
    WATCH -. feedback .-> SCORE

Loading

File-Level Changes

Change	Details	Files
Replaced the ASCII pipeline sketch in the README with a Mermaid architecture flowchart and added clarifying narrative for the core pipeline vs subsystems.	Introduced a Mermaid flowchart LR diagram showing the score → place → pack → quality gate → trace pipeline with 10 nodes and dashed subsystem edges. Annotated the diagram with a short explanation of the green core path and the roles of adaptive weights, cache topology, and drift/immune/council subsystems.	README.md
Improved cross-language structure documentation by adding a TS↔Python location mapping table in the README Python section.	Added a three-row table describing packages/, python/context_engineering/, and python/context_framework/ and their roles. Reworded Python section intro to emphasize two parity implementations and consistent algorithms between stacks.	README.md
Addressed two high-severity security alerts via dependency version bump and pnpm override.	Bumped http-proxy-middleware from ^4.0.0 to ^4.1.1 in package.json to pull in patched versions resolving multipart CRLF injection and host-routing bypass. Added a form-data: ">=4.0.6" entry to pnpm.overrides in package.json to enforce a secure minimum version across the workspace. Updated pnpm-lock.yaml to align with the new dependency constraints.	package.json pnpm-lock.yaml
Removed an unsafe, broken local symlink accidentally committed at the repo root.	Deleted the root-level claude symlink file that pointed to /Users/k/.local/bin/claude.	claude

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Review limit reached

@dr-gareth-roberts, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 55 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: Repository UI (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: cfa23751-b8bf-4295-aef3-7ff549be940f

📥 Commits

Reviewing files that changed from the base of the PR and between e3af23b and 8ad9b69.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (3)

• README.md
• claude
• package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch polish/repo-pack

---

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.}

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

Fixed security issues:

• form-data (link)
• http-proxy-middleware (link)

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Copilot]

Pull request overview

Documentation + security-polish pass that updates the repo’s top-level README for clearer architecture and TS↔Python positioning, while addressing high-severity dependency alerts via a targeted dependency bump and pnpm override.

Changes:

• Replace the README’s ASCII pipeline sketch with a Mermaid flowchart and updated explanation of the core score → place → pack → quality gate → trace pipeline.
• Clarify the TS workspace vs Python port vs applied Python runtimes via a mapping table in the README’s Python section.
• Mitigate security alerts by bumping http-proxy-middleware and enforcing form-data >=4.0.6 via pnpm overrides (and lockfile updates).

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 2 comments.

File	Description
README.md	Adds Mermaid architecture diagram + improves TS↔Python structure explanation.
package.json	Bumps http-proxy-middleware range and adds pnpm override for form-data.
pnpm-lock.yaml	Updates lockfile to reflect new override and dependency resolution changes.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.