chore: project skeleton — module contracts, docs plan, GPLv3

README.md

@@ -0,0 +1,66 @@
+# jmove
+
+**Move source files. Keep every import intact.**
+
+`jmove` is a fast, single-binary CLI that moves/renames source files in a
+project and rewrites all import statements that reference them — no IDE,
+no language server, no runtime dependencies. Built for humans *and* AI
+agents.
+
+## Why
+
+`git mv` moves the file but breaks every relative import pointing at it.
+IDE renames fix imports but need an IDE. Existing CLI alternatives either
+shell out to heavy language servers (bun/ts-morph, Rope, gopls,
+rust-analyzer) or refuse to preview what they will change.
+
+jmove's answer:
+
+- **Dry-run + unified diff** — see every change before it hits disk.
+- **Atomic apply with rollback** — imports are rewritten first, the file
+  moves last; any failure restores everything.
+- **AI-agent mode** — `--json` everywhere, stable error codes, exit codes,
+  and a machine-readable skill doc (`docs/SKILL.md`).
+- **Pure Rust, one binary** — no external toolchains to install.
+- **Java support** — the package/directory coupling nobody else automates
+  outside IntelliJ.
+
+## Install
+
+```sh
+cargo install jmove
+```
+
+## Usage
+
+```sh
+# Preview what a move would change
+jmove mv src/utils/parser.ts src/core/parser.ts --dry-run
+
+# Apply it
+jmove mv src/utils/parser.ts src/core/parser.ts
+
+# Java: jmove updates `package`, all `import`s and moves the file
+jmove mv src/com/example/utils/Parser.java src/com/example/core/Parser.java
+
+# Find broken imports (exit code 2 if any)
+jmove check
+
+# AI-agent workflow
+jmove mv src/foo.ts src/bar/foo.ts --dry-run --json
+jmove mv src/foo.ts src/bar/foo.ts --json
+jmove check --json
+```
+
+See [docs/EXAMPLES.md](docs/EXAMPLES.md) for more, and
+[docs/SKILL.md](docs/SKILL.md) if you are an AI agent.
+
+## Roadmap
+
+TypeScript/JavaScript first, then Java (open niche), Python, Go.
+`split` (automatic file decomposition) is planned — no tool does it.
+Full plan: [docs/PLAN.md](docs/PLAN.md).
+
+## License
+
+GPL-3.0-only. See [LICENSE](LICENSE).