Agent Chokepoints

Agent Chokepoints 🤖

This page is for AI coding agents and contributors. It summarizes the high-risk areas that have previously caused hangs, generated-command explosions, stale UI, or unsafe archive behavior.

Read this before changing menus, activation, settings navigation, token estimates, file collection, or packaging.

---

1. Do Not Reintroduce Token-Bucket Commands

Old behavior generated thousands of commands for dynamic token-count menu labels. That caused:

• huge package.json
• Command Palette pollution
• slow manifest parsing
• Cursor activation/settings hangs
• fragile build output

Current rule:

Token counts appear in the status bar and zip notifications, not in menu titles.

Allowed menu generation is only the small target-model layer.

Verify:

npm run test:menu-merge
npm run test:tokens

---

2. Manifest Size Is a Canary

package.slim.json is the editable source. package.json is generated by compile.

If package.json becomes huge, assume a generated command explosion or manifest merge regression.

Do not:

• add one command per token bucket
• add one command per folder count
• expose generated target commands in the Command Palette
• bypass package.slim.json as the source-of-truth manifest

---

3. Settings Navigation Must Not Race Token Scans

Export2AI intentionally guards settings navigation from heavy token scans.

Current protections:

• initial full scan is deferred after activation
• settings navigation in progress can defer scans
• post-settings refresh is delayed
• config changes clear pending estimates and cache

Do not remove these guards without proving settings navigation remains responsive.

Verify:

npm run test:settings-nav

---

4. Explorer Badges Aggregate Once

Optional Explorer token badges must not trigger one subtree scan per folder.

Current pattern:

1. collect included files once
2. tokenize files once
3. aggregate token counts into ancestor folders
4. cache folder totals
5. serve provideFileDecoration synchronously from cache

Do not add lazy per-folder scanning back.

Verify:

npm run test:explorer-badges

---

5. Soft-Delete Must Preserve Context and Block Secrets

Do not regress the v1.2.8/v1.2.9 safety model.

Must remain true:

• .github/**, .gitignore, .gitattributes, docs, tests, tools, README.md, AGENTS.md, and pyproject.toml can stay visible
• local .git/ internals are not exported
• default marker is outside .git/
• credential/key material still wins over repo-control inclusion
• symlinks are skipped
• empty excludePaths entries do not exclude the workspace root

Verify:

npm run test:soft-delete

---

6. Build Pipeline Order Matters

Expected high-level order:

generate menus → TypeScript compile → sync settings docs → merge package manifest

Do not invert this order unless tests are updated and the generated fields still match.

---

7. Documentation Rules for Agents

For docs-only work:

• do not edit src/, scripts/, tests/, or package manifests unless explicitly requested
• keep README compact, roughly under 160 lines
• move detailed explanations into wiki pages
• keep wiki/_Sidebar.md in sync with page files
• preserve technical docs in docs/
• do not upload or commit generated Export2AI context zips

---

8. Common Agent Mistakes Checklist

Before submitting changes, check that you did not:

• create a separate repository for wiki content
• commit the analysis zip or generated context zip
• delete technical details from docs without moving them to the wiki
• remove safety warnings from soft-delete docs
• claim token estimates are API-exact for approximate families
• turn Explorer token badges on by default
• make removeComments or compressCode default to true
• hide built-in excludes from user control
• restore .git/ as the default marker location

---

9. Required Smoke Tests for Risky Areas

Changed area	Minimum tests
token model/format	npm run test:tokens
soft-delete/excludes	npm run test:soft-delete
settings navigation	npm run test:settings-nav
Explorer badges	npm run test:explorer-badges
menu generation	npm run test:menu-merge
packaging/assets	npm run test:marketplace-assets, npm run package
broad change	npm run test:critical

When in doubt, run the full critical matrix.