# Nodarama Verbatim

## Authenticity and unsigned beta notice

This beta package is currently **unsigned**.

Until the alpha release is distributed with signed certificates, only trust a copy downloaded directly from:

`https://nodarama.com`

Windows and macOS may show security warnings because this beta is not yet code-signed. Do not run copies received from unofficial links, reuploads, unknown file shares, or modified zip packages.

---

## What it is

Nodarama Verbatim is a local-first coding companion for people using AI to create, edit, and manage software projects.

It is designed to help connect AI-written intent to real files on your system while keeping edits visible, reviewable, and reversible.

---

## Quick start on Windows

1. Install **Node.js LTS**:

   `https://nodejs.org`

2. Unzip Nodarama Verbatim somewhere simple, such as:

   `C:\NV`

3. Start Verbatim in visible mode:

   Double-click `power.bat`

This opens a command prompt so you can see startup output and errors.

---

## Hidden Windows startup shortcut

For a cleaner one-click launch without a visible terminal:

1. Run:

   `sysutil\create-windows-shortcut.ps1`

2. This creates a desktop shortcut named:

   `Nodarama Verbatim`

3. The shortcut launches Verbatim headlessly through:

   `sysutil\launch-verbatim-hidden.ps1`

The shortcut uses `favicon.ico` or `assets\favicon.ico` if one exists.

---

## Shutdown on Windows

If Verbatim was started headlessly, closing the browser window may not stop the backend services.

Use the shutdown helper:

`sysutil\power-off.ps1`

This calls the local shutdown script and stops the recorded Verbatim process IDs.

For visible command-prompt startup through `power.bat`, closing the terminal or pressing `Ctrl+C` should request shutdown, but the explicit power-off helper is the safest shutdown path.

---

## Quick start on macOS

1. Install **Node.js LTS**:

   `https://nodejs.org`

2. Unzip Nodarama Verbatim somewhere simple.

3. Start in visible terminal mode with:

   `power.command`

Or use the hidden launcher:

`sysutil/launch-verbatim-hidden.command`

---

## macOS app wrapper

To create a double-clickable macOS app wrapper:

1. Run:

   `sysutil/create-macos-app.sh`

2. It creates:

   `Nodarama Verbatim.app`

3. The app launches Verbatim headlessly through:

   `sysutil/launch-verbatim.js`

Icon support can be added later with an `.icns` file.

---

## Shutdown on macOS

If Verbatim was started headlessly, use:

`sysutil/power-off.command`

This stops the backend process IDs written during startup.

---

## Dependency install

If dependencies are missing, run:

`sysutil\install-dependencies.bat`

This checks Node/npm and installs the root package dependencies.

Most normal users should not need to run this manually if the package has already been prepared.

---

## Local AI setup: LM Studio

Nodarama Verbatim works best with a local model running through **LM Studio**.

1. Install LM Studio:

   `https://lmstudio.ai`

2. Download a chat/instruct model.

Good starting points are coding-capable instruct models in the 7B–14B range, depending on your computer.

3. Start the LM Studio local server.

Default expected URL:

`http://127.0.0.1:1234`

4. In Verbatim, confirm the LM Studio URL in Settings.

---

## Local app URL and ports

Verbatim starts a local Deck/UI server on your computer.

The runtime port may be chosen automatically unless a fixed port is configured in settings. The app opens the local UI after startup.

If you use a fixed Deck port, confirm it in Settings before using external bridge tools.

---

## Optional ChatGPT bridge with ngrok

The ChatGPT bridge is optional.

Only use ngrok if you intentionally want an outside service, such as ChatGPT, to reach your local Verbatim instance.

Be careful before sharing:

- ngrok URLs
- project files
- logs
- scrapes
- settings
- credentials
- API keys

If bridge access is enabled, confirm the runtime port shown by Verbatim before starting an ngrok tunnel.

---

## Folder layout

Important root files:

- `power.bat` — visible Windows startup
- `power.command` — visible macOS startup
- `power.ts` — main app boot file
- `Nodarama Verbatim.ps1` — root Windows hidden launcher
- `package.json` — npm scripts and dependencies

Support utilities live in:

`sysutil/`

User projects live in:

`projects/`

Future user-defined scripts should live in:

`scripts/`

---

## Packaging a beta zip

The packaging helper is:

`sysutil\zipit.bat`

It calls:

`sysutil\zipit.ps1`

Use this only when preparing a cleaned beta package. Review the generated staging folder before sharing a zip.

---

## Privacy notes

Nodarama Verbatim is intended to be local-first.

Before sharing a package or support bundle, check for:

- personal project contents
- logs
- scrapes
- settings
- user/auth files
- credentials
- tokens
- environment files
- ngrok URLs

Do not share private local files unless you intentionally prepared them for support or release.

---

## Troubleshooting

If startup fails:

1. Confirm Node.js LTS is installed.
2. Try visible startup with `power.bat` on Windows or `power.command` on macOS.
3. Run `sysutil\install-dependencies.bat` if dependencies are missing.
4. Make sure LM Studio is running if using local AI.
5. Confirm LM Studio is available at:

   `http://127.0.0.1:1234`

6. If a hidden launch leaves services running, use the matching power-off helper:

   Windows: `sysutil\power-off.ps1`

   macOS: `sysutil/power-off.command`

---

## Current status

This is a beta package.

Expect rough edges around startup shortcuts, shutdown behavior, unsigned operating-system warnings, and local environment differences. Signed releases are planned for a later alpha distribution.
