open-index/open-npm huggingface dataset:
npm package: @qnote/q-ai-note
Description: AI-assisted personal work sandbox and diary system
Latest version: 1.0.24

# q-ai-note

AI-assisted personal work sandbox and diary system.

## Documentation

Project specs and development guides are organized under `docs/`:

- `docs/spec/functional-spec.md`
- `docs/spec/design-spec.md`
- `docs/spec/ui-spec.md`
- `docs/process/development-guide.md`

## Install

Use without global install:

```bash
npx @qnote/q-ai-note
```

Install globally:

```bash
npm i -g @qnote/q-ai-note
q-ai-note
q-ai-note-server
```

## Usage

```bash
q-ai-note --port 3200
q-ai-note .
q-ai-note --readonly
```

Then open `http://localhost:3200`.

### Command differences

- `q-ai-note`: local-first, defaults `127.0.0.1:3000`
- `q-ai-note-server`: public server, defaults `0.0.0.0:8614`

### Public server mode

If you need external access, use:

```bash
q-ai-note-server
q-ai-note-server --readonly
```

Defaults:
- host: `0.0.0.0`
- port: `8614`

Then open `http://<server-ip>:8614`.

### Access control model

The app now uses two-level configuration:

- system config (`~/.q-ai-note/config.json`): model settings + `editable_ip_allowlist`
- project config (`<data-dir>/project-config.json`): `users` / `profiles` / `bindings`

Rules:
- IP matching is exact match only (no CIDR)
- local loopback and local NIC IPs are system-admin by default
- system-admin IPs can access all pages and full read/write (unless global `--readonly`)
- non-admin IPs are controlled by project profiles (page visibility + sandbox-level read/write)
- `/api/settings` (system settings) is only accessible to system-admin IPs

### Readonly mode

Use `--readonly` (or env `Q_AI_NOTE_READONLY=true`) to start in readonly mode:

- hide chat UI and chat buttons
- hide settings page
- hide add/edit/delete operations
- reject all write API requests (`403`)
- reject settings API (`/api/settings`) for readonly requests (`403`)

## Data and config paths

- Config: `~/.q-ai-note/config.json`
- Data dir: `~/.q-ai-note/data/`
  - `project-config.json`
  - `sandboxes.json`
  - `work-items.json`
  - `diaries.json`
  - `chats.json`
  - `chat-sandbox-relations.json`
  - `operations.json`

You can override runtime paths with environment variables:

- `Q_AI_NOTE_CONFIG_DIR`
- `Q_AI_NOTE_DATA_DIR`

Backward-compatible legacy variables are still supported:

- `PERSONAL_AI_NOTEBOOK_CONFIG_DIR`
- `PERSONAL_AI_NOTEBOOK_DATA_DIR`

## Publish to npm

```bash
npm login
npm publish --access public
```