docs: slim the README and move detail into docs/

The README had grown to 428 lines — good documentation, but too much to
read before deciding whether to try the tool, and it is also the npm
landing page.

It is now 219 lines covering what a newcomer needs: what the problem is,
quick start, whether to use this or the VS Code extension, the command
table, the safety model, and enough authentication to get a first run
working. Everything deeper moved out:

- docs/CONFIGURATION.md — config fields, id-to-path mapping, scriptRoot
  rules, patterns, editor/types setup
- docs/AUTHENTICATION.md — password sources, HTTPS, self-signed certs, CI
- docs/TROUBLESHOOTING.md — the things that look like bugs and are not,
  starting with 'logs shows nothing'
- docs/DEVELOPMENT.md — running from a clone, tests, invariants,
  contributing
- docs/AUTOMATION.md — expanded with the record shapes, which were
  previously only discoverable by reading the source

The 'Scripting and automation' section was the specific complaint: a long
teaser linking to a doc that said little more. The teaser is now four lines
and the detail is real.

docs/images/README.md is deleted — it described how to take the screenshot,
which now exists.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mschmicking

README.md

@@ -0,0 +1,68 @@
+# Authentication
+
+How `iob-sync` gets a password, and why it refuses to take one on the command line. See
+the [README](../README.md) for the overview.
+
+## Instances without authentication
+
+Nothing to do. `iob-sync` probes `<url>/login`; a 404 means authentication is disabled
+and no credential is needed.
+
+## Instances with authentication
+
+ioBroker will not accept a password over plain HTTP, so an authenticated instance is
+also on HTTPS — usually with a self-signed certificate. Set `allowSelfSigned: true`
+(interactive `init` offers this automatically), then save a password once:
+
+```bash
+iob-sync login       # prompts without echoing, verifies, then saves
+```
+
+`login` checks the password against the live instance **before** storing it, so a typo
+fails immediately rather than on the next command. `iob-sync logout` removes it.
+
+## Where the password is kept
+
+**Never in the project.** `.iobroker-sync.json` holds only the username. The password
+goes to `~/.config/iobroker-sync/credentials.json`, mode `0600` inside a `0700`
+directory, keyed by URL and username so several instances can be used from one machine.
+
+Override the location with `IOBROKER_SYNC_CREDENTIALS` — the test suite does this so it
+never touches a real store.
+
+## There is no `--password` flag
+
+Deliberately. `argv` is readable by any other local process via `ps`, and shells record
+it in history. The sources actually supported, in the order they are tried:
+
+| Source              | Use                                                                    |
+| ------------------- | ---------------------------------------------------------------------- |
+| `--password-stdin`  | scripts and CI: `printf '%s' "$PW" \| iob-sync --password-stdin login` |
+| `IOBROKER_PASSWORD` | ad-hoc shells                                                          |
+| saved credentials   | normal interactive use, after `iob-sync login`                         |
+| hidden prompt       | when nothing else is available and a terminal is attached              |
+
+Prompts require stdin **and** stdout to be TTYs, so a script, CI job or agent gets a
+clear error instead of hanging on an invisible prompt.
+
+## Which login path is used
+
+OAuth2 (`POST /oauth/token`) is tried first, falling back to the legacy `POST /login`
+session cookie used by older Admin versions. `--verbose` reports which one worked and
+where the password came from:
+
+```
+debug: authenticated via OAuth2 (/oauth/token), password from store
+```
+
+The legacy path is covered by tests but has never run against real hardware — current
+Admin authenticates via OAuth2.
+
+## Ports and certificates
+
+Connect to the **admin adapter** port, usually 8081 — not the socket.io adapter port
+(8084), which lacks the permissions this tool needs.
+
+`allowSelfSigned` applies to both the HTTPS login and the websocket. It accepts any
+certificate; there is no way to pin a specific one. Without it, an untrusted certificate
+fails before any credential is sent, and the error names the setting that fixes it.

docs/AUTHENTICATION.md

@@ -1,14 +1,13 @@
 # Scripting and automation
 
-Machine-readable output, and what it is for. See the
-[README](../README.md) for everything else.
+Machine-readable output, and what it is for. See the [README](../README.md) for the
+overview.
 
-Human output is for reading; `--json` is for everything else. It emits
-[NDJSON](https://ndjson.org) on stdout — one JSON object per line, each tagged with a
-`type`. Human text is suppressed and warnings/errors stay on stderr, so **stdout stays
-parseable even when a command fails**.
+`--json` puts [NDJSON](https://ndjson.org) on stdout — one JSON object per line, each
+tagged with a `type`. Human text is suppressed and warnings/errors stay on stderr, so
+**stdout stays parseable even when a command fails**.
 
-What that is actually for:
+## What it is actually for
 
 ```bash
 # Fail a CI job if anything drifted from git
@@ -25,10 +24,45 @@ iob-sync --json logs --level error
 ```
 
 It is also what makes the tool usable by a coding agent: an agent editing your scripts
-can read `status`, push, and then watch `logs` for a compile failure, without
-screen-scraping a table meant for a terminal.
+can read `status`, push, then watch `logs` for a compile failure, without screen-scraping
+a table meant for a terminal.
 
-Records carry underlying values rather than display strings — `enabled` is a boolean, not
-`"✓"`; `engine` is the full instance id, not `js.2`; and `--json status` includes the
-in-sync scripts the human view collapses into a count. NDJSON rather than one array
-because `logs` and `watch` never end; use `jq -s .` if you want a single document.
+## Record shapes
+
+Every record carries a `type` discriminator. Records hold underlying values rather than
+display strings — `enabled` is a boolean, not `"✓"`; `engine` is the full instance id,
+not `js.2`.
+
+| Command  | `type`   | Fields                                           |
+| -------- | -------- | ------------------------------------------------ |
+| `list`   | `script` | `id`, `path`, `engine`, `engineType`, `enabled`  |
+| `status` | `status` | `id`, `path`, `state`                            |
+| `pull`   | `pull`   | `id`, `path`, `dryRun`                           |
+| `push`   | `push`   | `id`, `path`, `created`, `dryRun`                |
+| `diff`   | `diff`   | `id`, `path`, `state`, `against` (snapshot mode) |
+| `backup` | `backup` | `snapshot`, `createdAt`, `scripts`, `entries`    |
+| `logs`   | `log`    | `message`, `severity`, `from`, `ts`              |
+
+`--json status` includes the in-sync scripts that the human view collapses into a bare
+count, so a consumer never has to re-run with `--verbose`.
+
+`dryRun` is present on anything that would have written, so a consumer cannot mistake a
+`--dry-run` rehearsal for a real change.
+
+## Why NDJSON rather than one array
+
+`logs` and `watch` never end. An array could never be closed, and nothing would appear
+until the process exited. Line-at-a-time also means an agent watching stdout sees
+progress as it happens.
+
+Use `jq -s .` to slurp the stream into a single document when you want one:
+
+```bash
+iob-sync --json list | jq -s 'map(select(.enabled)) | length'
+```
+
+## Exit codes
+
+`0` on success, `1` on a user-facing failure — a conflict needing `--force`, a missing
+config, a failed login. Errors go to stderr as human text, never as NDJSON, so a non-zero
+exit with empty stdout is unambiguous.

docs/AUTOMATION.md

@@ -0,0 +1,105 @@
+# Configuration
+
+Where files live, how ioBroker ids map to paths, and how to give your editor
+intellisense. See the [README](../README.md) for the overview.
+
+## The project folder
+
+`iob-sync` is a global command that works on a **project folder** — the folder holding
+`.iobroker-sync.json`. Where the tool itself is installed is irrelevant; nothing is ever
+read from or written to `node_modules`.
+
+```
+~/iobroker-scripts/            <- project root: run iob-sync anywhere inside it
+├── .iobroker-sync.json        <- config. Commit it; it holds no password.
+├── .iobroker-sync/            <- state, backups, trash. Gitignored; may contain secrets.
+└── scripts/                   <- scriptRoot: your scripts land here
+    ├── common/garage.ts
+    └── Switch-Musiccast.js
+```
+
+Commands search upward from the current directory for `.iobroker-sync.json`, the way
+`git` finds `.git`, so you can run them from any subfolder. `-C <dir>` runs as if started
+somewhere else.
+
+## `.iobroker-sync.json`
+
+| Field             | Meaning                                                            |
+| ----------------- | ------------------------------------------------------------------ |
+| `url`             | Admin base URL including scheme and port, e.g. `https://host:8081` |
+| `scriptRoot`      | Folder for synced scripts, relative to the project root            |
+| `allowSelfSigned` | Accept an untrusted TLS certificate                                |
+| `username`        | Admin username, or `null` when authentication is disabled          |
+| `defaultInstance` | javascript instance assigned to newly created scripts              |
+
+Commit this file — it holds no password. Credentials live outside the project entirely;
+see [AUTHENTICATION.md](AUTHENTICATION.md).
+
+## `scriptRoot` cannot escape the project
+
+Absolute paths and `../` are rejected. `scriptRoot` is the directory the tool writes
+into, so a config pointing outside could drop files anywhere on your disk.
+
+This means you do not point an existing project at a scripts folder elsewhere — you run
+`init` **in** the folder you want to keep scripts in:
+
+```bash
+cd ~/iobroker-scripts     # your git repo
+iob-sync init             # config lands here, scriptRoot defaults to "scripts"
+```
+
+### If that folder already contains files
+
+Safe, but worth knowing: when a script would land on top of a file you already have and
+the two differ, `pull` reports a **conflict** and leaves your file alone. `--force` takes
+the server's copy. Identical files are adopted silently.
+
+Setting `scriptRoot` to `.` works, but scripts then land beside your `README.md` and
+`package.json`. A subfolder is tidier and keeps `status` output readable.
+
+## How ids map to files
+
+| ioBroker object                                | local file                    |
+| ---------------------------------------------- | ----------------------------- |
+| `script.js.common.garage` (`TypeScript/ts`)    | `scripts/common/garage.ts`    |
+| `script.js.Switch-Musiccast` (`Javascript/js`) | `scripts/Switch-Musiccast.js` |
+
+Script folders are ioBroker `channel` objects; nested folders map to nested directories.
+`Blockly` and `Rules` scripts are pulled as `.block` / `.rules` for completeness, but
+their sources are generated XML/JSON and are not meant to be hand-edited.
+
+Sources are normalised to LF before hashing and upload, so a CRLF checkout does not show
+every script as modified.
+
+## Patterns
+
+Patterns match case-insensitively against both the ioBroker id and the local path. A
+pattern without `*` matches as a substring (`iob-sync diff garage`); one containing `*`
+is an anchored glob (`iob-sync status 'common/*.ts'`).
+
+## Editor support
+
+Straight after a `pull` an editor does not know what `log`, `schedule`, `on` or
+`getState` are — they exist only inside the javascript adapter's sandbox, so every script
+shows `Cannot find name 'log'`. Fix it once:
+
+```bash
+iob-sync types
+```
+
+That downloads the adapter's own typings to `.iobroker/types/` and writes
+`<scriptRoot>/tsconfig.json`, so any LSP client — neovim, VS Code, Helix, Zed — picks
+them up. **Restart your language server afterwards.**
+
+`init --types` does the same during setup. `iob-sync types` exists so you can add or
+refresh them later without touching a working config. `--force` replaces an existing
+`tsconfig.json`; `--offline` skips the download.
+
+### Why the generated config sets `moduleDetection: force`
+
+Each ioBroker script runs in its own sandbox scope, but to TypeScript a folder of plain
+scripts shares one global scope — so two scripts each declaring `const helper` would
+collide with TS2451, an error about code that is perfectly fine at runtime. Module
+semantics give every file its own scope, matching how the adapter actually runs them.
+`module`/`target` are `es2022` rather than `commonjs` because the adapter permits
+top-level `await`, which commonjs rejects with TS1378.

docs/CONFIGURATION.md

@@ -0,0 +1,82 @@
+# Development
+
+Running `iob-sync` from a clone, and working on the tool itself. See the
+[README](../README.md) for what it does.
+
+## Running it from a clone
+
+Until the package is on npm, this is how to try it:
+
+```bash
+git clone https://github.com/mschmicking/iobroker-sync
+cd iobroker-sync
+npm install
+npm run build
+npm link            # puts `iob-sync` on your PATH from your working copy
+```
+
+**Then leave this directory.** `iob-sync` operates on whatever folder you run it in, so
+`init` belongs in your _scripts_ folder, not in the clone:
+
+```bash
+cd ~/iobroker-scripts     # your own folder — create it if it does not exist
+iob-sync init
+iob-sync pull
+```
+
+Running `init` inside the clone makes the tool's own repository the project root, and
+`scriptRoot` cannot point outside it — so there is no way to reach scripts kept
+elsewhere. If you have already done that, delete the stray `.iobroker-sync.json`,
+`.iobroker-sync/` and `scripts/` from the clone and start again in the right folder.
+
+If you would rather not `npm link`, call the built entry point directly and let `-C`
+choose the project:
+
+```bash
+node /path/to/iobroker-sync/dist/cli.js -C ~/iobroker-scripts list
+```
+
+## Working on the tool
+
+```bash
+npm test            # build + full suite
+npm run test:unit   # pure-logic tests only
+npm run lint
+npm run format
+npm run verify      # lint + format check + typecheck + tests
+```
+
+`npm test` builds `dist/` as well as `dist-test/`, because `test/cli.test.ts` spawns the
+real binary.
+
+Every test runs against an in-process fake Admin server (`test/fake-server.ts`); **no
+test may touch a real instance.** The TLS suite generates a self-signed certificate on
+first run via `openssl` and caches it under `test/fixtures/`; without `openssl` it skips
+rather than fails.
+
+## Invariants the tests exist to protect
+
+Do not weaken these without a deliberate decision:
+
+- `pull` never deletes a local file, and never silently overwrites one.
+- `push` sends only `common.source` and `common.engineType` — never `enabled` or
+  `engine`. `ObjectsApi.extendScript` is typed to enforce it, so a sync bug structurally
+  cannot stop a running script or move it between javascript instances.
+- Conflicts refuse and exit non-zero rather than guessing.
+- Only `remove`, `rename` and `move` delete anything; each needs `--yes` and writes the
+  object to `.iobroker-sync/trash/` first.
+- `watch` suppresses the adapter's own `compiled`/`sourceHash` write-back. A regression
+  there means an infinite push loop against a live instance.
+
+Commands never call `console.*` — output goes through `ctx.log`, which is what makes
+`--json` and the tests possible. ESLint enforces this everywhere except `cli.ts`.
+
+## Contributing
+
+Pull request titles must be [conventional commits](https://www.conventionalcommits.org/)
+(`feat:`, `fix:`, `docs:`, `chore:` …) — the title becomes the squashed commit message
+and drives the version bump, and a workflow validates it. PRs are squash-merged.
+
+**[AGENTS.md](../AGENTS.md)** has the full picture: the Admin wire protocol, why each
+lint rule is on or off, and what is deliberately untested. Read it before changing sync
+logic.