jpsync 1.0.0__tar.gz

jpsync-1.0.0/.gitignore

@@ -0,0 +1,58 @@
+# Local agent / editor state
+.claude/
+
+# Byte-compiled / optimized / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+*.egg
+
+# Build artifacts
+build/
+dist/
+*.pyz
+*.spec
+
+# Distribution binaries produced by PyInstaller (anchored to repo root so the
+# `src/jp/` package directory is NEVER ignored)
+/jp
+/jp.exe
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Editors / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/
+.serena/
+
+# Secrets / credentials -- NEVER commit a token
+*.token
+*token*
+.jupyter_token
+.env
+.env.*
+
+# jp workspace metadata (created in a user's synced folder, never in this repo)
+.jp/
+
+# Internal research notes and scratch (kept locally, not published)
+research/
+refine_review_workflow.js
+
+# uv lockfile (project is zero-dependency; not tracked)
+uv.lock

jpsync-1.0.0/CHANGELOG.md

@@ -0,0 +1,113 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0](https://github.com/pehqge/jpsync/compare/v0.3.1...v1.0.0) (2026-05-31)
+
+
+### Miscellaneous Chores
+
+* rebrand PyPI package and repo to jpsync ([a26db5c](https://github.com/pehqge/jpsync/commit/a26db5c4981f462e5695d7432e003426dac694eb))
+
+## [0.3.1](https://github.com/pehqge/jpsync/compare/v0.3.0...v0.3.1) (2026-05-31)
+
+
+### Bug Fixes
+
+* **readme:** use shields static/v1 badge so release-please can't eat the color ([7c9377b](https://github.com/pehqge/jpsync/commit/7c9377b860b5f75942a93c662b7bdab5b7afa83f))
+* **update:** detect editable installs instead of faking a successful upgrade ([d12722b](https://github.com/pehqge/jpsync/commit/d12722b47d9ba6192198c1062e01502f4d87be22))
+
+## [0.3.0](https://github.com/pehqge/jpsync/compare/v0.2.0...v0.3.0) (2026-05-31)
+
+
+### Features
+
+* **kernel:** add --link, fix docs, print privacy verdict ([13d42ca](https://github.com/pehqge/jpsync/commit/13d42cab82df2463d444c5387da59609e8a84e12))
+* **kernel:** add `jp kernel` to fix VS Code remote-kernel cwd ([7ba887c](https://github.com/pehqge/jpsync/commit/7ba887c782d7cdf341e262fbd398609d8e7d0864))
+
+
+### Bug Fixes
+
+* **credentials:** skip world-readable warning on Windows ([44fa06a](https://github.com/pehqge/jpsync/commit/44fa06a4af1b9f3983bfaad12e1a9380257f36c9))
+* **readme:** use a static release badge auto-bumped by release-please ([1176d07](https://github.com/pehqge/jpsync/commit/1176d07d4885562db9dd2f4fb9ccfab9128a97ee))
+* **tests:** isolate Windows home dir and simplify release badge ([9eeb6ac](https://github.com/pehqge/jpsync/commit/9eeb6acbd7931ee30384b6c74dd9c3214805e425))
+* **tests:** keep USERPROFILE comment within ruff line-length ([86f3d68](https://github.com/pehqge/jpsync/commit/86f3d68fea3614e930a1d06278ba11017f8d02bb))
+
+
+### Documentation
+
+* fix jp login flow to match actual behavior ([c378c4e](https://github.com/pehqge/jpsync/commit/c378c4e7538632155a17fd1d70a28901fe7fac40))
+* fix two more stale README details ([1fefd67](https://github.com/pehqge/jpsync/commit/1fefd6719a35457f374ffc33d7ec3ad244910781))
+* **readme:** add FAQ entry for the VS Code remote-kernel workflow ([d4e0436](https://github.com/pehqge/jpsync/commit/d4e043644df21357d39156964954a164c68d3cfa))
+
+## [0.2.0](https://github.com/pehqge/jpsync/compare/v0.1.0...v0.2.0) (2026-05-31)
+
+
+### Features
+
+* **config:** activate color setting and add dotfile "protect" policy ([38c9ac7](https://github.com/pehqge/jpsync/commit/38c9ac7ebe963156e0eb92015ec98c147d617a00))
+* named credentials with interactive jp login ([ec290db](https://github.com/pehqge/jpsync/commit/ec290db9233c427a7150ecebb3cfad836d4b0e68))
+
+
+### Bug Fixes
+
+* add top-level release-type to release-please config ([695d456](https://github.com/pehqge/jpsync/commit/695d456d42511a371a33bad1d3e327af61c45b88))
+* tag releases as vX.Y.Z without component prefix ([c2e9794](https://github.com/pehqge/jpsync/commit/c2e9794065feb93f13afa24a947f5db26bae820c))
+* **tui:** repair interactive settings render and add navigation hints ([0e6b673](https://github.com/pehqge/jpsync/commit/0e6b673ab1bab1ad4e396679b1874b1284b93cf7))
+
+
+### Documentation
+
+* replace real JupyterHub URL with generic example placeholder ([54612b7](https://github.com/pehqge/jpsync/commit/54612b7e269d8e8f2c1e4757c6427aeaec625314))
+
+## [Unreleased]
+
+### Added
+
+- Named credentials: `jp login` is now interactive — it explains how to get a
+  JupyterHub API token, reads it with hidden input, asks for a name, and saves it
+  **globally** (`~/.config/jp/`) or **locally** (a workspace's `.jp/`). Token
+  values are written to private `600` files and never leave the machine; only the
+  credential name is recorded in config. Scriptable via `--name`,
+  `--global`/`--local`, `--token-stdin`, `--token-path`, `--force`.
+- `jp clone` / `jp init` select a saved credential automatically when only one
+  exists, or prompt to choose when several do (`--credential <name>` to skip the
+  prompt); the choice is recorded in the workspace config.
+- New `credential` config key and a `credentials.json` registry per scope.
+- Every `.jp/` workspace now gets a `.jp/.gitignore` (`*`) so a workspace that is
+  also a git repo can never commit its local state or a local token file.
+
+### Changed
+
+- Token resolution order is now `$JP_TOKEN` → `$JP_TOKEN_FILE` → the workspace's
+  saved credential → legacy `token_path` / `~/.config/jp/token` (the legacy paths
+  remain supported).
+
+## [0.1.0] - 2026-05-30
+
+### Added
+
+- Initial release of `jp` (PyPI package `jpsync`, command `jp`).
+- Git-like commands: `clone`, `pull`, `push`, `status`, `diff`, `init`,
+  `config`, `auth`, `version`.
+- Three-way sync model (local / remote / base) with conflict detection.
+- Conflict-safe synchronization: conflicting files are never overwritten
+  silently (exit code `6`).
+- Token-based authentication resolved as `--token-file` > `$JP_TOKEN_FILE` /
+  `$JUPYTER_TOKEN` > repo config > global config > `~/.jupyter_token`;
+  only the token path is stored in config, and the token file is expected to be
+  mode `0600`.
+- Path-jail confinement: remote paths are resolved inside the clone root, with
+  `..` traversal, absolute paths, and boundary-crossing symlinks rejected.
+- `.jpignore` support plus built-in defaults (`.jp/`, dotfiles, `.git/`,
+  `__pycache__/`, `*.pyc`); hidden files opt-in via `allow_hidden`.
+- Pure standard-library HTTP client (`urllib`) for the Jupyter Contents API,
+  with retry/backoff on network errors.
+- Distribution via PyPI, a single-file `jp.pyz` zipapp, standalone per-OS
+  PyInstaller binaries, and `install.sh` / `install.ps1` installers.
+
+[Unreleased]: https://github.com/pehqge/jpsync/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/pehqge/jpsync/releases/tag/v0.1.0

jpsync-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gimenez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jpsync-1.0.0/PKG-INFO

@@ -0,0 +1,406 @@
+Metadata-Version: 2.4
+Name: jpsync
+Version: 1.0.0
+Summary: A git-like CLI to sync local folders with a remote JupyterHub via the Contents API.
+Project-URL: Homepage, https://github.com/pehqge/jpsync
+Project-URL: Repository, https://github.com/pehqge/jpsync
+Project-URL: Issues, https://github.com/pehqge/jpsync/issues
+Project-URL: Changelog, https://github.com/pehqge/jpsync/blob/main/CHANGELOG.md
+Author-email: Pedro Gimenez <pehqge@gmail.com>
+Maintainer-email: Pedro Gimenez <pehqge@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,contents-api,jupyter,jupyterhub,notebook,sync
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">jp</h1>
+
+<p align="center">
+  <em>A git-like CLI to safely sync local folders with a remote JupyterHub — zero dependencies, pure Python.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/pehqge/jpsync/actions/workflows/ci.yml"><img src="https://github.com/pehqge/jpsync/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/pehqge/jpsync/releases/latest"><img src="https://img.shields.io/static/v1?label=release&message=v1.0.0&color=blue" alt="Release"></a> <!-- x-release-please-version -->
+  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
+  <a href="https://github.com/pehqge/jpsync/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero dependencies">
+</p>
+
+---
+
+`jp` keeps a local folder in sync with a directory on a **JupyterHub** server —
+the way `git` keeps you in sync with a remote. You edit notebooks and scripts on
+your laptop, `jp push` to send them up, run your training on the server's GPUs,
+and `jp pull` the results back down.
+
+It talks to the JupyterHub REST API directly, has **zero third-party
+dependencies** (pure Python standard library), and runs anywhere Python 3.9+
+runs — macOS, Windows, Linux.
+
+```console
+$ jp clone https://jupyter.example.com/user/you/lab/tree/your-folder
+cloning your-folder -> ./your-folder
+✓ clone: 12 transferred
+
+$ cd your-folder
+$ # ...edit files locally...
+$ jp push
+  push: train.py
+  push: data/config.yaml
+✓ push: 2 transferred, 10 up to date, 0 skipped, 0 conflict(s), 0 failed
+```
+
+## Why jp?
+
+- **Git-like workflow** — `jp clone`, `jp status`, `jp push`, `jp pull`. Same muscle memory.
+- **Safe by default** — on a *shared* research machine, jp never deletes remote files unless you explicitly turn that on, and even then it asks you file-by-file. Conflicts are never silently overwritten.
+- **Zero dependencies** — one install, no dependency hell; ships as a wheel, a single `.pyz`, or a standalone binary.
+- **Cross-platform** — macOS, Windows, Linux; Python 3.9 → 3.13.
+
+---
+
+## Installation
+
+> Recommended: install in an isolated environment with **uv** or **pipx** so the
+> `jp` command lands on your `PATH` without touching system Python.
+
+**With uv** (fastest):
+```bash
+uv tool install jpsync
+```
+
+**With pipx**:
+```bash
+pipx install jpsync
+```
+
+**Straight from GitHub** (before the first PyPI release):
+```bash
+pipx install "git+https://github.com/pehqge/jpsync"
+# or:  uv tool install "git+https://github.com/pehqge/jpsync"
+```
+
+**Install script (macOS / Linux)** — downloads the standalone binary, no Python needed:
+```bash
+curl -fsSL https://raw.githubusercontent.com/pehqge/jpsync/main/scripts/install.sh | sh
+```
+
+**Install script (Windows, PowerShell)**:
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/pehqge/jpsync/main/scripts/install.ps1 | iex"
+```
+
+**Single file, no install** — grab `jp.pyz` from the
+[latest release](https://github.com/pehqge/jpsync/releases/latest) and run it
+with any Python 3.9+:
+```bash
+python jp.pyz --help
+```
+
+Verify:
+```bash
+jp --version
+```
+
+> If `jp: command not found` after a pipx/uv install, run `pipx ensurepath` (or
+> `uv tool update-shell`) and reopen your terminal.
+
+---
+
+## Getting started
+
+### 1. Get your JupyterHub API token
+
+`jp` authenticates with a personal API token from your JupyterHub.
+
+1. Open your JupyterHub in a browser and log in (e.g. `https://jupyter.example.com`).
+2. Go to the **Token** page — usually the **Token** link in the top bar, or
+   visit `https://<your-hub>/hub/token` directly.
+3. Type a note (e.g. `jp`), leave the scopes blank (full access to what *you*
+   can already do), and click **Request new API token**.
+4. **Copy the token now** — JupyterHub shows it only once.
+
+> Security: the token is like a password for your account. `jp` stores only the
+> *path* to a token file, never the token value, and never logs or commits it.
+
+### 2. Log in with `jp login`
+
+Run `jp login` and follow the prompts. It asks for a short name, walks you
+through getting the token, then you paste it (your input stays **hidden**).
+Credentials are saved **globally** by default (usable from anywhere); pass
+`--local` to keep it only in the current workspace:
+
+```console
+$ jp login
+Name this server/credential (e.g. myserver): myserver
+To get a JupyterHub API token:
+  1. Open your JupyterHub in a browser and log in.
+  2. Go to the Token page (the 'Token' link, or <your-hub>/hub/token).
+  3. Click 'Request new API token' and copy it (it is shown only once).
+
+Paste your API token (input hidden):
+✓ saved global credential 'myserver'
+```
+
+**Everything stays on your machine.** `jp` writes the token to a private file
+(permissions `600`) under `~/.config/jp/` (or the workspace's `.jp/` for a local
+credential) and records only the credential's *name* in config — never the token
+value. The token is never printed, logged, committed, or sent anywhere except as
+the `Authorization` header to your own hub.
+
+Run `jp login` again any time to add another server — keep as many credentials as
+you like and pick one when you clone. See [Credentials](#credentials--jp-login).
+
+### 3. Make sure your server is running
+
+`jp` talks to your *single-user* server, so it must be started: open JupyterHub
+and, if needed, click **Start My Server**. (`jp doctor` will tell you if it's
+stopped.)
+
+### 4. Clone your folder
+
+Copy the URL of the folder from your browser's address bar — the `lab/tree/...`
+URL works directly:
+
+```bash
+jp clone https://jupyter.example.com/user/<you>/lab/tree/your-folder
+cd your-folder
+```
+
+That creates a `your-folder/` folder with a `.jp/` workspace inside (like `.git/`)
+and downloads the remote tree. If you saved more than one credential, `jp` asks
+which one to use; with a single one it just uses it. The choice is remembered in
+the workspace (`jp clone … --credential <name>` to skip the prompt).
+
+### 5. Work like git
+
+```bash
+jp status          # what changed, locally vs the server
+jp push            # send local changes up
+jp pull            # bring remote changes (e.g. training output) down
+```
+
+That's it. From any subdirectory of the workspace, `jp` finds its root
+automatically (it walks up looking for `.jp/`, stopping at your home folder).
+
+---
+
+## Command reference
+
+| Command | What it does |
+|---|---|
+| `jp clone <url> [dir]` | Clone a remote Jupyter folder into a new local directory. Accepts a `lab/tree` URL or `--base-url`/`--prefix`. |
+| `jp init <url>` | Turn the current folder into a jp workspace (no download). |
+| `jp login` | Save a named API-token credential (name the server, paste the token; defaults to global; use `--local` for workspace-only). |
+| `jp status` | Show local vs. remote differences. Read-only. |
+| `jp push` | Upload local changes. Additive by default. |
+| `jp pull` | Download remote changes. Additive by default. |
+| `jp diff [path]` | Show file-level differences. |
+| `jp ls [remote-path]` | List a remote directory (no local writes). |
+| `jp config` | Interactive settings editor (see below). Also `config get/set/list`. |
+| `jp ignore [pattern]` | Manage `.jpignore` patterns. |
+| `jp rm <path>` | Delete on the remote — gated, dry-run + typed confirmation. The only deleter. |
+| `jp kernel` | Set up a VS Code remote kernel to run notebooks in the right directory ([guide](docs/vscode-remote-cwd.md)). |
+| `jp doctor` | Diagnose token, connectivity, server status. |
+| `jp update` | Update jp to the latest version. |
+| `jp version` | Print the version (also `jp --version`). |
+
+Global flags: `-q/--quiet`, `--no-color`. Every command has `--help`.
+
+### `jp config` — interactive settings
+
+Run `jp config` with no arguments in a terminal for a settings screen:
+
+```
+  Mirror mode (allow deletes)              false
+> Dotfile policy                           skip
+  Colored output                           auto
+  Network timeout (s)                      30.0
+
+Up/Down move · Space change · i info · / search · Enter save · Esc cancel
+```
+
+- **↑/↓** move · **Space** cycle the value · **i** show help for the selected
+  setting · **/** search · **Enter** save · **Esc** cancel.
+
+For scripts, the classic forms still work: `jp config list`,
+`jp config get <key>`, `jp config set <key> <value>`.
+
+### Mirror mode (deleting files to match the other side)
+
+By default `jp push`/`jp pull` are **additive** — they never delete. If you want
+true mirroring (delete on the remote when you delete locally, and vice-versa),
+turn on **mirror mode**:
+
+```bash
+jp config set mirror true      # persist it, or use --mirror for one run
+jp push --mirror               # one-off
+```
+
+With mirror on, after the normal sync jp finds files that exist on one side but
+not the other and — **always, before deleting anything** — shows you the list
+and lets you choose, with the arrow keys, which to **keep** and which to
+**delete**:
+
+```
+Mirror mode: 2 file(s) exist on remote but not on the other side.
+Choose which to DELETE on remote. Default is KEEP.
+
+> [keep]   old_experiment.py
+  [keep]   scratch.ipynb
+
+Up/Down move · Space toggle · a delete-all · n keep-all · Enter confirm · Esc cancel
+```
+
+Nothing is deleted unless you mark it. In a non-interactive shell, mirror
+deletions are refused unless you pass `--yes`. Conflicts (both sides changed) are
+*never* deleted or overwritten.
+
+### Credentials & `jp login`
+
+`jp login` is how you give `jp` your JupyterHub API token. It is fully
+interactive and **everything happens locally** — the token never leaves your
+machine and is never printed:
+
+- You give the credential a **name** (usually the server, e.g. `myserver`).
+- It shows you how to get a token, then prompts you to paste it with the input
+  **hidden** (no echo).
+- The **scope** defaults to **global** (stored in `~/.config/jp/`, usable from
+  any directory). Pass `--local` to store the credential only in the current
+  workspace's `.jp/`.
+- The token value goes into a private `600` file; only its *name* is recorded in
+  the workspace config (`credential` key).
+- A **local** credential lives in the workspace's `.jp/`, and `jp` drops a
+  `.jp/.gitignore` (`*`) so that — even if the workspace is also a git repo — git
+  ignores the whole `.jp/` directory and the token can never be committed.
+
+Save as many as you like — run `jp login` once per server:
+
+```bash
+jp login                                      # interactive: name, paste token; saves globally
+jp login --name myserver --global             # scriptable form
+jp login --token-stdin --name lab-gpu --local < token.txt
+```
+
+When you `jp clone` / `jp init`, `jp` reads the credentials available **globally
+and locally**: with one it's used automatically, with several you pick which
+server to use (or pass `--credential <name>`). The choice is saved in the
+workspace so later `push`/`pull` just work.
+
+At sync time the token is resolved, in order: `$JP_TOKEN` (a value, for CI) →
+`$JP_TOKEN_FILE` (a path) → the workspace's saved credential → legacy
+`token_path` / `~/.config/jp/token`. `jp` warns if any token file is readable by
+other users.
+
+### Keeping jp up to date
+
+```bash
+jp update           # detects pipx / uv / pip and upgrades in place
+jp update --check   # just check; don't install
+```
+
+For a standalone binary install, `jp update` prints the one-line reinstall
+command for your OS.
+
+---
+
+## Configuration
+
+Each workspace stores its settings in `.jp/config.json` (JSON, never the token
+value). Keys: `base_url`, `prefix`, `credential`, `token_path`, `mirror`,
+`dotfiles`, `color`, `timeout`. See [docs/commands.md](docs/commands.md) and
+[docs/architecture.md](docs/architecture.md).
+
+---
+
+## Security
+
+`jp` is built for a **shared** machine where a mistake can destroy someone
+else's research. The guarantees:
+
+- **`push`/`pull` never delete** unless you opt into mirror mode — and even then
+  jp asks you, file by file, defaulting to keep.
+- **Conflicts are never silently overwritten.** If both sides changed since the
+  last sync, jp aborts that file and tells you.
+- **Path-jailing.** Every remote operation is confined to your workspace's
+  prefix. The server root and shared spaces (`compartilhado`, `lapix`,
+  `shared`, …) are refused outright.
+- **Untrusted server on download.** File names from the server are sanitized
+  before anything is written locally (anti path-traversal / Zip-Slip), and
+  writes are atomic and never follow a symlink.
+- **Your token never leaks** — stored by path only, sent in the `Authorization`
+  header (never a URL), redacted from all output, never committed.
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md) — please don't open a
+public issue.
+
+---
+
+## FAQ
+
+**Is `jp` related to git?** No — it borrows git's *workflow*, not its internals.
+There's no remote version history on a JupyterHub.
+
+**Does it need Jupyter installed locally?** No. Just Python 3.9+; it talks to the
+Hub over HTTPS.
+
+**Why won't my `.gitignore` (or any dotfile) upload?** Most JupyterHub servers
+run with `allow_hidden=False`, which rejects creating hidden files (names
+starting with `.`). `jp` detects this and *skips* dotfiles on push, reporting
+them instead of failing — your `.git/`, `.gitignore`, `.env` etc. simply stay
+local (which is usually what you want). A nice side effect: secrets in dotfiles
+never get pushed by accident.
+
+**Will it overwrite my work?** Never silently. A conflict aborts that file;
+remote deletes are opt-in (mirror mode) and confirmed file-by-file.
+
+**Can I edit notebooks locally in VS Code but run them on the remote GPUs?** Yes —
+that's a core workflow. Sync with jp, then connect VS Code to your remote kernel.
+One catch: a remote kernel starts in the server's home, not your notebook's
+folder, so relative paths fail. Run `jp kernel` once to fix it. The full
+walkthrough (connecting the kernel + the cwd fix) is in
+[docs/vscode-remote-cwd.md](docs/vscode-remote-cwd.md).
+
+## Troubleshooting
+
+- **`jp: command not found`** — run `pipx ensurepath` / `uv tool update-shell`, reopen the terminal.
+- **`your JupyterHub server appears to be stopped`** — open the Hub UI and click *Start My Server*.
+- **`authentication failed` / HTTP 403** — your token expired; create a new one and `jp login` again (or update the token file).
+- **A big upload times out** — raise the timeout: `jp config set timeout 120`.
+- **`FileNotFoundError` / relative paths fail in VS Code with a remote kernel** — the kernel starts in the server's home, not your notebook's folder. Run `jp kernel` (see the [VS Code remote-kernel guide](docs/vscode-remote-cwd.md)).
+
+Run `jp doctor` for a guided check.
+
+---
+
+## Contributing
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). The project is standard-library only;
+please keep it dependency-free.
+
+## License
+
+[MIT](LICENSE) © Pedro Gimenez