@polterware/polterbase 0.2.4 → 0.2.6

package/README.md

@@ -18,17 +18,31 @@ Polterbase is a productivity layer on top of the official `supabase` CLI. Instea
 - **Global Flags Picker**: Add common global flags in one step
 - **Pinned Commands and Runs**: Toggle base command pins with `→` and pin exact runs after success
 - **Custom Command Mode**: Run raw Supabase arguments like `-v` or `status -o json`
-- **Shell Execution**: Executes your local `supabase` binary directly
+- **Built-in Self-Update**: Update Polterbase for the current repository or globally through npm
+- **Shell Execution**: Resolves `supabase` from the current repository first, then falls back to `PATH`
 - **TypeScript-based CLI**: Strongly typed internal implementation
+- **App Workflows**: Explicit `polterbase app ...` flows for repository-aware setup, linking, migrations, runtime configuration, and app installation
 
 ---
 
 ## Installation
 
-### Run without installing globally
+### Run one-off without installing
 
 ```bash
-npx @polterware/polterbase
+npx @polterware/polterbase@latest
+```
+
+### Install in a repository
+
+```bash
+npm install -D @polterware/polterbase
+```
+
+Then run it from that repository with:
+
+```bash
+npx polterbase
 ```
 
 ### Install globally
@@ -43,28 +57,36 @@ Then run:
 polterbase
 ```
 
-`polterbase` is a global CLI tool. Do not add it to `dependencies` or `devDependencies` of app projects.
+Use a repository install when you want the CLI version pinned to one project.
+Use a global install when you want the same CLI version across every repository.
 
 ### Update
 
-If you run Polterbase with `npx`, always use the latest published version explicitly:
+If you installed it globally, update it with:
 
 ```bash
-npx @polterware/polterbase@latest
+npm install -g @polterware/polterbase@latest
 ```
 
-If you installed it globally, update it with:
+If you installed it in a repository, update it there with:
 
 ```bash
-npm install -g @polterware/polterbase@latest
+npm install -D @polterware/polterbase@latest
 ```
 
+You can also run the same update flow from inside Polterbase:
+
+1. Go to the `Actions` section
+2. Choose `Update Polterbase`
+3. Choose `Current repository` or `Global install`
+4. Confirm the npm update command
+
 ---
 
 ## Requirements
 
 - **Node.js**: `>= 18`
-- **Supabase CLI**: installed and available in `PATH`
+- **Supabase CLI**: installed globally in `PATH` or locally in the current repository
 
 Check your environment:
 
@@ -81,14 +103,57 @@ Install Supabase CLI (official docs):
 
 ## Quick Reference
 
+### App Workflows
+
+Polterbase keeps generic Supabase execution separate from app-specific automation.
+Use the `app` namespace when you want project-aware workflows:
+
+```bash
+polterbase app setup uru --path .
+```
+
+```bash
+polterbase app link uru --path .
+```
+
+```bash
+polterbase app migrate uru push --path .
+```
+
+```bash
+polterbase app configure uru --path .
+```
+
+```bash
+polterbase app install uru --platform macos
+```
+
+`setup uru` installs dependencies, collects Supabase connection data, links the project, pushes migrations, and writes the runtime bootstrap payload used by the desktop app.
+
+`configure uru` refreshes the runtime connection payload without reinstalling the app.
+
+`install uru` is currently macOS-only. By default it resolves the latest GitHub release from `polterware/uru`, accepts `--version <version>` to pin a release, and still supports `--artifact-url` or `POLTERBASE_URU_MACOS_ARTIFACT_URL` as manual overrides.
+
+Use `POLTERBASE_URU_GITHUB_REPO=owner/repo` when you need to resolve releases from a fork or a different repository.
+
 ### Execution Model
 
-Polterbase always executes commands as:
+Polterbase executes workflow commands as:
 
 ```bash
 supabase <command> <extra-args> <global-flags>
 ```
 
+The self-update action is the only built-in exception and can run one of:
+
+```bash
+npm install -g @polterware/polterbase@latest
+```
+
+```bash
+npm install -D @polterware/polterbase@latest
+```
+
 ### Typical Flow
 
 1. Choose a command from the unified board
@@ -189,6 +254,30 @@ Pins are persisted locally using OS-level app config storage.
 
 ## Usage Examples
 
+### Bootstrap Uru from source
+
+```bash
+polterbase app setup uru --path /absolute/path/to/uru
+```
+
+### Reconfigure an installed Uru app
+
+```bash
+polterbase app configure uru
+```
+
+### Install the latest released Uru app
+
+```bash
+polterbase app install uru --platform macos
+```
+
+Install a specific release:
+
+```bash
+polterbase app install uru --platform macos --version 1.0.0
+```
+
 ### Check Supabase CLI version
 
 Interactive path:
@@ -252,11 +341,11 @@ supabase db pull --yes
 
 ### `supabase: command not found`
 
-Supabase CLI is not installed or not in your `PATH`.
+Supabase CLI is not installed in the current repository and is not available in your `PATH`.
 
 Fix:
 
-1. Install Supabase CLI
+1. Install Supabase CLI globally or in the current repository
 2. Restart terminal
 3. Run `supabase --version`