chore: repo review fixes — lint, CI, doc currency, organization

.eslintrc.json

@@ -12,5 +12,14 @@
     "@typescript-eslint/no-explicit-any": "warn",
     "@typescript-eslint/explicit-function-return-type": "off",
     "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
-  }
+  },
+  "overrides": [
+    {
+      "files": ["**/__tests__/**/*.ts", "**/*.test.ts"],
+      "rules": {
+        "@typescript-eslint/no-explicit-any": "off",
+        "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }]
+      }
+    }
+  ]
 }

.github/copilot-instructions.md

@@ -223,7 +223,7 @@ Docs live in `docs/` — see `docs/index.md` for the full structure.
 Before creating a release, verify the following:
 
 1. **CHANGELOG is up to date** — all merged PRs and features are listed under `[Unreleased]`; promote `[Unreleased]` → `[X.Y.Z] - YYYY-MM-DD`
-2. **Version bumped** — update `package.json`, this file (`copilot-instructions.md`), and `PLAN.md`
+2. **Version bumped** — update `package.json`, this file (`copilot-instructions.md`), and `dev-notes/PLAN.md`
 3. **Tests pass** — run `npm test` and confirm all tests pass
 4. **Build succeeds** — run `npm run build` to compile TypeScript and update `dist-action/`
 5. **Commit, tag, push** — commit all changes, create git tag `vX.Y.Z`, push with `--tags`

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Verify dist-action bundle is up to date
+        run: |
+          if [ -n "$(git status --porcelain dist-action)" ]; then
+            echo "::error::dist-action/ is out of date. Run 'npm run build' and commit the result."
+            git --no-pager diff -- dist-action
+            exit 1
+          fi

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Thanks for your interest in improving **action-translation**! This guide covers
+the local workflow for code, tests, and documentation.
+
+## Prerequisites
+
+- Node.js 20 (matches the GitHub Actions `node20` runtime)
+- npm
+
+## Setup
+
+```bash
+git clone https://github.com/QuantEcon/action-translation.git
+cd action-translation
+npm install
+```
+
+## Development workflow
+
+```bash
+npm test             # Run the full Jest suite (~1005 tests)
+npm run lint         # ESLint (must pass with no errors)
+npm run build        # tsc compile (dist/) + esbuild bundle (dist-action/index.js)
+npm run build:cli    # CLI-only TypeScript compile (dist/)
+npm run format       # Prettier
+```
+
+Before opening a pull request, make sure `npm run lint`, `npm test`, and
+`npm run build` all succeed. CI runs the same checks on every PR.
+
+### Rebuilding the action bundle
+
+The GitHub Action runs from the committed `dist-action/index.js` bundle. If you
+change any source under `src/`, **rebuild and commit the bundle**:
+
+```bash
+npm run build
+git add dist-action
+```
+
+CI fails if `dist-action/` is out of date relative to the source.
+
+## Pull requests
+
+1. Branch from `main` (e.g. `fix/short-description` or `feat/short-description`).
+2. Keep changes focused; add or update tests for behavior changes.
+3. Update relevant docs under [`docs/`](docs/) and the [CHANGELOG](CHANGELOG.md)
+   (under the `[Unreleased]` heading).
+4. Ensure lint, tests, and build pass.
+5. Open the PR against `main` with a clear description.
+
+## Tests
+
+Tests live in `src/__tests__/` and `src/cli/__tests__/`. See
+[docs/developer/testing.md](docs/developer/testing.md) for structure and
+conventions on writing new tests.
+
+## Contributing glossary terms
+
+Translation glossaries live in [`glossary/`](glossary/). See
+[glossary/README.md](glossary/README.md) for the file format, quality
+guidelines, and the process for adding terms or new languages.
+
+## Architecture
+
+For a tour of the modules, operational modes, and data flow, read
+[docs/developer/architecture.md](docs/developer/architecture.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+project's [MIT License](https://opensource.org/licenses/MIT).

README.md

@@ -2,7 +2,7 @@
 
 A GitHub Action and CLI tool for managing translations of MyST Markdown documents using Claude AI.
 
-**Version**: v0.11.2 | **Tests**: 909 (39 suites) | [Full Documentation](docs/)
+**Version**: v0.15.0 | **Tests**: 1005 (39 suites) | [Full Documentation](docs/)
 
 ## What it does
 
@@ -44,7 +44,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: quantecon/action-translation@v0.11
+      - uses: quantecon/action-translation@v0
         with:
           mode: sync
           target-repo: 'quantecon/lecture-python.zh-cn'
@@ -87,9 +87,8 @@ See the [Quickstart guide](docs/user/quickstart.md) for full setup instructions.
 
 ```bash
 npm install          # Install dependencies
-npm test             # Run all 909 tests
-npm run build        # Compile TypeScript
-npm run package      # Bundle for distribution
+npm test             # Run all 1005 tests
+npm run build        # Compile TypeScript + bundle the action (dist-action/)
 ```
 
 ## License

dev-notes/README.md

@@ -0,0 +1,12 @@
+# Developer notes
+
+Internal working documents — design plans, roadmaps, and historical fix
+write-ups. These are **not** part of the published documentation site
+(`docs/`) and are kept here for maintainers' reference.
+
+| File | Description |
+|------|-------------|
+| [PLAN.md](PLAN.md) | Detailed development roadmap and phase tracking. Maintained by the team — see the document header for the version it was last updated against. |
+| [FIX-ISSUE-63.md](FIX-ISSUE-63.md) | Historical write-up of the rebase-on-merge fix (issue #63), shipped in v0.15.0. |
+
+For user-facing and architectural documentation, see [`docs/`](../docs/).

docs/developer/architecture.md

@@ -4,7 +4,7 @@ title: Architecture
 
 # Architecture
 
-**Last Updated**: 6 March 2026 — v0.11.2  
+**Last Updated**: 14 April 2026 — v0.15.0  
 
 This document covers the complete system architecture: design philosophy, operational modes, module structure, data flow, and key design decisions.
 
@@ -310,8 +310,8 @@ API calls use exponential backoff retry (3 attempts: 1s, 2s, 4s delays):
 ### ESM + CJS dual build
 
 The CLI uses ESM (required by `ink` v4 for interactive rendering). The GitHub Action uses CJS (required by the Actions runtime). The build system produces both:
-- `npm run build:cli` → ESM via `tsc` (CLI)
-- `npm run package` → CJS via `esbuild` (`dist-action/index.js`)
+- `npm run build:cli` → ESM via `tsc` (CLI, outputs `dist/`)
+- `npm run build` → `tsc` then `esbuild` (compiles `dist/` **and** bundles the CJS action at `dist-action/index.js`)
 
 ## Parser internals
 
@@ -380,10 +380,9 @@ Only sections detected as changed are sent to Claude for translation. This typic
 ## Build and packaging
 
 ```bash
-npm run build        # TypeScript compilation
-npm run build:cli    # CLI ESM build
-npm run package      # Action CJS bundle (dist-action/index.js)
-npm test             # Run all 909 tests
+npm run build        # tsc compile (dist/) + esbuild bundle (dist-action/index.js)
+npm run build:cli    # CLI-only TypeScript compile (dist/)
+npm test             # Run all 1005 tests
 ```
 
 The action is distributed as a single bundled file (`dist-action/index.js`) with no external dependencies at runtime. Glossary files are included in `dist-action/glossary/`.

docs/developer/testing.md

@@ -4,7 +4,7 @@ title: Testing
 
 # Testing
 
-**Current**: 724 tests | 32 suites | ~2s execution time
+**Current**: 1005 tests | 39 suites | ~4s execution time
 
 ## Running tests
 

docs/projects/README.md

@@ -124,7 +124,7 @@ Summer students would likely focus on **Project A** (the most coding-intensive),
 
 ## Related Documents
 
-- [PLAN.md](../../PLAN.md) -- Development roadmap for `action-translation`; Phase 9 discusses whole-file vs section-by-section translation architecture, and `experiments/forward/` contains initial experiment results that Project A should build on
+- [PLAN.md](../../dev-notes/PLAN.md) -- Development roadmap for `action-translation`; Phase 9 discusses whole-file vs section-by-section translation architecture, and `experiments/forward/` contains initial experiment results that Project A should build on
 - [_archive/PROJECT-BENCHMARK.md](_archive/PROJECT-BENCHMARK.md) -- Original comprehensive benchmark plan with detailed infrastructure specs (CI/CD, issue templates, provider interfaces, dashboard mockup) -- useful reference when implementing
 - [architecture.md](../developer/architecture.md) -- `action-translation` module structure
 - [testing.md](../developer/testing.md) -- How the action's test suite works

docs/user/action-reference.md

@@ -111,7 +111,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-intro.zh-cn'
@@ -148,7 +148,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-intro.zh-cn'
@@ -165,7 +165,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-intro.fa'
@@ -192,7 +192,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: review
           source-repo: 'QuantEcon/lecture-python-intro'
@@ -207,7 +207,7 @@ jobs:
 ### Using outputs
 
 ```yaml
-- uses: QuantEcon/action-translation@v0.11
+- uses: QuantEcon/action-translation@v0
   id: translate
   with:
     mode: sync

docs/user/glossary.md

@@ -63,7 +63,7 @@ Each term has:
 To use your own glossary instead of (or in addition to) the built-in one, specify the `glossary-path` input:
 
 ```yaml
-- uses: QuantEcon/action-translation@v0.11
+- uses: QuantEcon/action-translation@v0
   with:
     mode: sync
     glossary-path: 'glossary/my-custom-glossary.json'

docs/user/language-config.md

@@ -73,4 +73,4 @@ Each language configuration has:
 After adding a language configuration, you should also:
 1. Create a glossary file at `glossary/{code}.json` (see [Glossary](glossary.md))
 2. Add test cases for the new language
-3. Rebuild the action (`npm run build && npm run package`)
+3. Rebuild the action (`npm run build`)

docs/user/quickstart.md

@@ -50,7 +50,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'YourOrg/your-repo.zh-cn'
@@ -83,7 +83,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: review
           source-repo: 'YourOrg/your-source-repo'

docs/user/tutorials/add-language.md

@@ -146,8 +146,7 @@ For Japanese, you would add a font entry if matplotlib's default fonts don't ren
 After editing the source:
 
 ```bash
-npm run build       # Compile TypeScript
-npm run package     # Bundle for distribution (updates dist-action/)
+npm run build       # Compile TypeScript + bundle the action (updates dist-action/)
 npm test            # Run all tests
 ```
 
@@ -246,7 +245,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-python-intro.zh-cn'
@@ -264,7 +263,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-python-intro.ja'
@@ -295,7 +294,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 2
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: review
           source-repo: 'QuantEcon/lecture-python-intro'
@@ -389,7 +388,7 @@ Each target repository maintains its own `.translate/state/` independently.
 - [ ] Glossary created at `glossary/{code}.json`
 - [ ] Language rules added to `src/language-config.ts` (optional)
 - [ ] Font configuration added if needed (optional)
-- [ ] Source rebuilt: `npm run build && npm run package`
+- [ ] Source rebuilt: `npm run build`
 - [ ] Target repo scaffolded: `translate setup`
 - [ ] Content translated: `translate init`
 - [ ] Translated content pushed to target repo

docs/user/tutorials/connect-existing.md

@@ -373,7 +373,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-python-intro.zh-cn'
@@ -416,7 +416,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: review
           source-repo: 'QuantEcon/lecture-python-intro'

docs/user/tutorials/fresh-setup.md

@@ -283,7 +283,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: sync
           target-repo: 'QuantEcon/lecture-python-intro.zh-cn'
@@ -329,7 +329,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: QuantEcon/action-translation@v0.11
+      - uses: QuantEcon/action-translation@v0
         with:
           mode: review
           source-repo: 'QuantEcon/lecture-python-intro'