# Maintaining the skill

> Self-improvement protocol for deobfuscate-javascript: when to update CHUNK_NAME_REGISTRY, fix scripts with tests, append caveats or codex-ref notes, commit discipline, and legal constraints on extracted Codex source.

- Repository: JimLiu/decode-codex
- GitHub: https://github.com/JimLiu/decode-codex
- Human docs: https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33
- Complete Markdown: https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/llms-full.txt

## Source Files

- `.agents/skills/deobfuscate-javascript/SKILL.md`
- `.agents/skills/deobfuscate-javascript/scripts/resolve-npm-imports.ts`
- `.agents/skills/deobfuscate-javascript/scripts/quality-gate.test.ts`
- `.agents/skills/deobfuscate-javascript/reference/caveats.md`
- `.agents/skills/deobfuscate-javascript/reference/codex-ref.md`
- `README.md`

---

---
title: "Maintaining the skill"
description: "Self-improvement protocol for deobfuscate-javascript: when to update CHUNK_NAME_REGISTRY, fix scripts with tests, append caveats or codex-ref notes, commit discipline, and legal constraints on extracted Codex source."
---

The `deobfuscate-javascript` skill under `.agents/skills/deobfuscate-javascript/` is a living asset: agents running any restoration tier are expected to route discoveries back into the skill (scripts, registry, reference docs) so the next run benefits. The canonical protocol lives in `SKILL.md` under **Maintaining this skill (self-improvement protocol)**; this page operationalizes that contract for maintainers and agents.

<Note>
Skill maintenance is separate from restoration output. `ref/` and `restored/` are gitignored generated artifacts — commit skill changes and restoration checkpoints in different commits with different message conventions.
</Note>

## Three triggers

Update the skill when a restoration surfaces any of these:

| Trigger | Examples |
| --- | --- |
| **Obvious problem** | Script bug, `quality-gate.ts` or Stage 3 acceptance misfire, wrong flag/path in a stage or workflow doc |
| **Process optimization** | Manual step repeated across chunks that a script flag or pipeline ordering change could automate |
| **New npm package** | Vendored chunk whose stripped basename is missing from `CHUNK_NAME_REGISTRY`, or an external tool worth adopting |

The skill explicitly instructs agents: fix the skill itself, not only the current output, then commit under the discipline below.

## Route each finding to its home

| Finding | Destination |
| --- | --- |
| New vendored npm package | `CHUNK_NAME_REGISTRY` and optionally `ALIAS_REGISTRY` in `scripts/resolve-npm-imports.ts`; refresh `npm-leaf` examples in `SKILL.md` and `stages/stage-2-restore.md` |
| Script bug or misfiring gate | Fix under `scripts/`; add or extend `scripts/<name>.test.ts` |
| Wrong or stale documentation | Edit `SKILL.md`, stage docs, or workflow docs inline |
| Edge case or gotcha | Append to `reference/caveats.md` |
| Codex- or project-specific learning | Append to `reference/codex-ref.md` (boundary fingerprints, Pierre/Radix fork notes, semantic domain hints) |
| New automated step | Implement in the relevant script; document in stage/workflow docs; update routing and tools tables in `SKILL.md` if the flow changes |
| New JS/Babel dependency | Add to `package.json` and run `bun install` in the skill directory |
| New external binary (wakaru, webcrack, prettier, …) | Thin wrapper script with graceful degradation (model: `format.ts`, `wakaru-normalize.ts`); pin version in the invoke command; document under **Tools at a glance → External tools** — do not `bun install` Rust/Go CLIs |

```text
Restoration finding
        │
        ├─ data-only (registry, caveats, codex-ref, doc fix) ──► apply inline; safe mid-run
        ├─ behavior-changing script ──► fix + *.test.ts + bun test ──► commit skill
        └─ too risky mid-run ──► TODO in doc; keep restoration moving
```

## When to update CHUNK_NAME_REGISTRY

`CHUNK_NAME_REGISTRY` in `scripts/resolve-npm-imports.ts` is the authoritative map from stripped chunk basenames to npm specifiers. It drives:

- `resolve-npm-imports.ts` — rewrites `import … from "./clsx-DDuZWq6Y.js"` to bare `clsx`
- `build-import-graph.ts` — classifies reachable chunks as `npm-leaf` (BFS stops; chunk is not restored as app code)
- `check-entry.ts` — treats known registry entries as npm leaves, not local app chunks

### Basename extraction

`extractChunkBasename()` strips the path segment, file extension, then an 8-character Vite/Rollup hash (with a 10–12 character fallback). Multi-word names like `react-dom-De86Q4ix` become `react-dom`, not `react`.

### Registry entry shape

Each key is the **stripped basename** (hash-free), not the full filename:

<ParamField body="package" type="string" required>
Bare npm specifier to rewrite imports to (e.g. `"clsx"`, `"@dnd-kit/core"`, `"react/jsx-runtime"`).
</ParamField>

<ParamField body="defaultName" type="string">
Default local binding when the chunk has a default export and the alias is unknown (e.g. `clsx`, `React`, `Fuse`).
</ParamField>

<ParamField body="namedOnly" type="boolean">
When `true`, every specifier from the chunk is treated as a named import (e.g. `tslib`, `jsx-runtime`, `@floating-ui/react-dom`).
</ParamField>

### When to add an entry

Add to the registry when:

1. Stage 2/3 polish leaves `import … from "./some-pkg-HASH.js"` that should be a bare npm import.
2. `build-import-graph.ts` incorrectly classifies a known vendor chunk as `local` and BFS descends into package internals.
3. `codex-ref.md` documents a bundled third-party boundary whose basename stem does not match the registry (e.g. `isEqual-*` → `lodash`, `lib-*` → `react-intl`) — register the stem and prefer a `make-facade.ts --reexport` deliverable over deep-restoring vendor code.

<Warning>
Before registering `@pierre/*`, `@radix-ui/*`, or `zod` (`src-*`), confirm the chunk is stock npm, not a Codex fork. A wrong bare rewrite is harder to undo than leaving the local path. See `reference/codex-ref.md` fork caveats.
</Warning>

### ALIAS_REGISTRY

When the chunk basename is project-local (e.g. `./shared`) but the **local binding** is a well-known export (`useState`, `_React`, `FormattedMessage`), add or extend `ALIAS_REGISTRY` with `package`, `style`, and optional `renameLocalTo`.

### One-run workaround

Until the registry is updated, pass `--treat-as-npm <basename>` to `build-import-graph.ts` so a single run treats listed basenames as `npm-leaf` without descending. This is a stopgap — still add the permanent registry entry and a test.

<Steps>
<Step title="Identify the stripped basename">

Inspect the chunk path (e.g. `./react-hook-form-AbCdEf12.js` → `react-hook-form`). Cross-check `ref/package.json` dependencies when restoring Codex `./ref`.

</Step>

<Step title="Add CHUNK_NAME_REGISTRY and ALIAS_REGISTRY entries">

Choose `defaultName` vs `namedOnly` from how consumers import the chunk. Add cryptic alias mappings to `ALIAS_REGISTRY` when exports use minified local names.

</Step>

<Step title="Extend tests">

Add cases to `scripts/resolve-npm-imports.test.ts` (rewrite behavior) and `scripts/build-import-graph.test.ts` (`npm-leaf` classification). Existing tests cover `clsx`, `react-dom` hash anchoring, and `--treat-as-npm` overrides.

</Step>

<Step title="Refresh docs">

Update `npm-leaf` examples in `SKILL.md` and the chunk-name lookup section in `stages/stage-2-restore.md`. For Codex-specific vendor tables, append to `reference/codex-ref.md`.

</Step>

<Step title="Run the suite and commit">

```bash
cd .agents/skills/deobfuscate-javascript
bun test
```

Commit with `skill(deobfuscate-javascript): add <package> to CHUNK_NAME_REGISTRY`.

</Step>
</Steps>

## Fix scripts with tests

Behavior-changing script edits must ship with a green `bun test` run from `.agents/skills/deobfuscate-javascript/`. The skill ships 37 `scripts/*.test.ts` files plus `fixtures/` for Stage 1 techniques (packer, AAEncode, string-array, composite, control-flow-flat, and others).

| Area | Test file | What to extend |
| --- | --- | --- |
| Import resolution | `resolve-npm-imports.test.ts` | New registry entries, `extractChunkBasename` edge cases |
| Graph classification | `build-import-graph.test.ts` | `npm-leaf` vs `local`, `--treat-as-npm`, hash regression |
| Quality bar | `quality-gate.test.ts` | New issue codes, provenance rules, full-restoration coverage |
| Stage 1 | `unpack.test.ts`, `string-array.test.ts`, `deobfuscate.test.ts`, … | New obfuscation patterns — add a `fixtures/<technique>.min.js` fixture when extending matchers |

<RequestExample>

```bash
cd .agents/skills/deobfuscate-javascript
bun test                          # full suite
bun test scripts/quality-gate.test.ts   # single file
```

</RequestExample>

For a misfiring `quality-gate.ts` check: reproduce with a minimal source string in `quality-gate.test.ts` (the suite already tests provenance headers, cryptic params, duplicate headers, and CLI `--allow-missing-provenance`). Never commit with a red suite.

Non-standard string-array rotation patterns called out in `reference/caveats.md` should get a `fixtures/` sample so the matcher extension cannot regress.

## Append caveats and codex-ref notes

**`reference/caveats.md`** is the cross-stage FAQ: pipeline ordering, eval safety in `unpack.ts`, Prettier `.gitignore` traps, wakaru byte-offset shifts, polish tier differences, and troubleshooting entries. Append a new subsection when you discover a gotcha that will recur — do not bury one-off fixes only in restoration chat.

**`reference/codex-ref.md`** is the project profile for `./ref` (openai-codex-electron): entry discovery, Pierre/`@radix-ui` boundary fingerprints, bundled-vendor re-export table, semantic domain playbook, and Stage 3 acceptance expectations for this repo. Append when you learn:

- A basename trap (looks like Pierre but is Codex app code, or vice versa)
- A new bundled third-party boundary and its npm specifier
- Default command-frame or resume conventions that changed with a Codex.app update

Stage docs (`stages/stage-2-restore.md`, `stages/stage-3-finalize.md`) link back to the self-improvement protocol for missed npm packages — keep those links accurate when you extend the registry.

## Safety guards during an active restoration

| Change type | Mid-run policy |
| --- | --- |
| Registry entries, caveats, codex-ref, doc-only fixes | Safe to apply inline |
| Behavior-changing script | Requires green `bun test` before commit; do not leave suite red |
| Risky or unvalidated refactor | Smallest safe note (TODO in relevant doc); do not block the user's restoration on speculative work |

Data-only edits do not alter the in-flight pipeline. Script behavior changes can invalidate checkpoints, manifest offsets, or gate results — validate before relying on them in the same session.

## Commit discipline

At the end of each agent turn, commit — but **separate skill self-improvements from restoration output**:

| Commit kind | Message convention | Contents |
| --- | --- | --- |
| Skill maintenance | `skill(deobfuscate-javascript): <what changed>` | Scripts, tests, `SKILL.md`, `reference/*`, `package.json` |
| Restoration progress | `app-main: …` (repo convention) | Promoted files under `restored/`, `IMPORT_MAP.json`, public deliverables |

<Check>
Never commit `restored/.deobfuscate-javascript/` workspace intermediates. The whole `restored/` tree is gitignored; staging checkpoints, manifests, and per-chunk `$WS` dirs stay local.
</Check>

Skill commits should be reviewable in isolation: one logical change (e.g. one registry package, one gate fix) per commit when practical.

## Legal constraints on extracted Codex source

This repository is for **personal study and interoperability research** of software you have installed. The extracted Codex.app bundle is © OpenAI; respect the Codex desktop app license and terms of service.

| Rule | Implementation in this repo |
| --- | --- |
| Do not redistribute extracted or restored code | `ref/` and `restored/` are listed in `.gitignore` — regenerated by skills, not checked in |
| Do not publish OpenAI proprietary source | Skill commits contain tooling and documentation only; not `ref/webview/assets` chunks or full `restored/` trees |
| Refresh from your own install | `codex-app-ref-refresh` reads `/Applications/Codex.app/Contents/Resources/app.asar` locally |

<Warning>
A `make-facade.ts --passthrough` interim deliberately makes `restored/` depend on unrestored `ref/` chunks (`@ts-nocheck` + `// TODO`). That is a local development stopgap, not a license to redistribute either tree.
</Warning>

Maintainers improving the skill should never use skill commits as a channel to leak extracted app source. Registry keys and fixture snippets must be minimal and technique-focused, not full vendor bundles.

## Verification checklist

Before closing a skill-maintenance turn:

1. `bun test` exits 0 from `.agents/skills/deobfuscate-javascript/`.
2. New npm basenames appear in `CHUNK_NAME_REGISTRY` (and tests), not only `--treat-as-npm` overrides.
3. Recurring gotchas are in `reference/caveats.md` or `reference/codex-ref.md`, not only inline in one workflow.
4. Commit message uses the `skill(deobfuscate-javascript):` prefix and excludes `ref/` / `restored/` artifacts.

## Related pages

<CardGroup>
<Card title="Import graph and boundaries" href="/import-graph-and-boundaries">
How `CHUNK_NAME_REGISTRY` feeds `npm-leaf` classification, facade lifecycle, and quality-gate coverage.
</Card>
<Card title="Codex project profile" href="/codex-project-profile">
When to extend `codex-ref.md` with Pierre, Radix, and bundled-vendor boundary notes.
</Card>
<Card title="Pipeline caveats" href="/pipeline-caveats">
Ordering rules and failure modes that belong in `reference/caveats.md`.
</Card>
<Card title="Quality bar and anti-patterns" href="/quality-bar-and-anti-patterns">
Completion criteria and gate failures that often drive script fixes.
</Card>
<Card title="External tools and dependencies" href="/external-tools-and-dependencies">
How to adopt new Bun deps vs external binary wrappers.
</Card>
</CardGroup>