# Tagvico AI V3 documentation

> Official documentation snapshot intended for language-model context. Follow the section matching the installed major version.

<!-- Source: /docs/index.html.md -->

---
layout: home

hero:
  name: "Tagvico v3.2"
  text: "A calmer workspace for Paperless-ngx"
  tagline: File documents, research your archive, organize tags and keep every sensitive change visible.
  image:
    src: /tagvico-icon.png
    alt: Tagvico AI
  actions:
    - theme: brand
      text: Install v3.2.0
      link: /installation
    - theme: alt
      text: Explore features
      link: /features
    - theme: alt
      text: Choose a provider
      link: /providers

features:
  - icon: 🗂️
    title: Documents to useful work
    details: Process documents, find the original, track deadlines and keep restore history in one workspace.
  - icon: ✅
    title: Ask Tagvico
    details: Ask about documents and obligations while every Paperless search, document read and proposed write stays visible.
  - icon: 🔌
    title: Your model, your boundary
    details: Tagvico owns the safe harness. Use Vercel AI SDK providers such as OpenCode Go or an optional read-only Codex SDK adapter.
  - icon: 📈
    title: Visible operations
    details: Keep the established metadata automation, review queue, processing history, OCR recovery, retry controls, and restoration tools.
  - icon: 💬
    title: Optional Telegram access
    details: Give allowlisted family members cited search, uploads, action lists, and approve/reject controls through their own Paperless tokens.
---

## Start here

Tagvico is a self-hosted action layer for an existing Paperless-ngx instance.
It keeps Paperless as the document system of record while adding household
ownership, checklists, deadlines, approval history, and a provider-neutral AI
session runtime. Existing reviewable AI metadata filing remains available.

This page tracks the latest stable v3 patch release. The version menu keeps
older major-version guides available, while [Release notes](./release-notes)
shows exactly what changed in v3.2.

::: tip Production defaults
Pin the immutable `3.2.0` image, back up the data volume before upgrades, and start new installations in
**Review first** mode. Companion writes are always approval-gated regardless
of the metadata processing mode.
:::

---

<!-- Source: /docs/installation.md -->

# Install Tagvico v3

You need Docker Compose, a running Paperless-ngx installation, its base URL,
and a Paperless API token. Tagvico runs as one container and stores its local
configuration, admin account, history, and queues in a persistent volume.

## 1. Create the Compose file

Create a new directory and save this as `docker-compose.yml`:

```yaml
services:
  tagvico-ai:
    image: ghcr.io/arturict/tagvico-ai:3.2.0
    container_name: tagvico-ai
    restart: unless-stopped
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges=true
    ports:
      - "8080:3000"
    environment:
      TAGVICO_AI_PORT: "3000"
      ALLOW_REMOTE_SETUP: "yes"
    volumes:
      - tagvico_ai_data:/app/data

volumes:
  tagvico_ai_data:
```

Pin the exact v3 tag you intend to run. Do not use `latest` for a
production install because it makes upgrades and rollback ambiguous.

## 2. Start and check the container

```bash
docker compose up -d
docker compose ps
curl http://localhost:8080/health
```

Open `http://localhost:8080/setup` after the health check succeeds.

This sanitized capture shows the local admin sign-in presented after setup. It
contains no credentials, private hostnames, document data, or account details.

The same container also serves the documentation bundled with that release.
Open `http://localhost:8080/docs/` or the `/documentation` alias. The docs do
not depend on a separate hosted documentation service, so they keep matching
the image you pinned even when the public website changes.

## 3. Finish guided setup

1. Enter the Paperless base URL without `/api`, then paste a Paperless API token
   and test the connection.
2. Choose a [model provider](./providers) and enter its credentials or endpoint.
3. Create the local Tagvico owner account.
4. After signing in, use **Settings → Automation** to select **Review first**
   for approval-based filing or **Automatic** for direct writes, then choose
   which metadata fields Tagvico may change.

After saving the provider, inspect the detailed application health response.
Unlike `/health`, this endpoint reports the configured model adapter's health
when that adapter exposes a health check:

```bash
curl --fail http://localhost:8080/api/health
```

Some compatible and subscription-backed adapters report their health as
unknown rather than making a billable test request. Use the **Test connection**
actions in Settings to verify both Paperless and the selected model provider
before processing documents.

If Paperless runs on the Docker host, use `host.docker.internal` on Docker
Desktop or the host's LAN address on Linux. If both containers share a Docker
network, use the Paperless Compose service name.

::: tip Safer first run
Use **Review first**, enable only a small controlled tag vocabulary, and test
with synthetic or non-sensitive documents before allowing automatic writes.
:::

## Optional Telegram bot

Create a bot with BotFather, obtain each person's Telegram numeric user ID, and
create a separate Paperless API token for each person. Add the following
environment values to the Tagvico service:

```yaml
environment:
  TELEGRAM_BOT_ENABLED: "yes"
  TELEGRAM_BOT_TOKEN: "123456:replace-with-the-bot-token"
  TELEGRAM_USERS_JSON: >-
    [{"telegramId":"123456789","paperlessToken":"one-users-paperless-token","householdId":"copy-from-settings","memberId":"copy-from-settings"}]
  # Optional: bypasses the Tagvico review queue for metadata on bot uploads.
  TELEGRAM_UPLOAD_AUTOMATIC_METADATA: "no"
```

The remaining optional tuning variables are
`TELEGRAM_POLL_TIMEOUT_SECONDS` (default `30`),
`TELEGRAM_UPLOAD_TIMEOUT_SECONDS` (default `180`),
`TELEGRAM_MAX_DOCUMENTS` (default `8`), `TELEGRAM_HISTORY_TURNS`
(default `6`), and `TELEGRAM_MAX_FILE_BYTES` (default `20971520`). The bundled
Compose file passes every Telegram setting through to the application container.

`paperlessUrl` may be added to an individual allowlist entry; otherwise the
normal `PAPERLESS_API_URL` is used. Restart Tagvico after changing this process
configuration. A Telegram entry linked to the Action Center must use the same
Paperless instance as the main configuration. The standard Telegram Bot API can download uploads up to 20 MB,
and Tagvico enforces that limit. Unknown IDs and non-private chats receive no
response.

Read [Privacy and security](./privacy) before enabling the bot. Telegram bot
chats are not end-to-end encrypted, and model-provider data terms still apply.

## Docker run alternative

```bash
docker volume create tagvico_ai_data
docker run -d \
  --name tagvico-ai \
  --restart unless-stopped \
  --cap-drop ALL \
  --security-opt no-new-privileges=true \
  -p 8080:3000 \
  -e TAGVICO_AI_PORT=3000 \
  -e ALLOW_REMOTE_SETUP=yes \
  -v tagvico_ai_data:/app/data \
  ghcr.io/arturict/tagvico-ai:3.2.0
```

After setup, remove `ALLOW_REMOTE_SETUP=yes` unless you specifically need to
repeat setup from another machine.

## Next steps

- Compare the [supported providers](./providers) and understand where document
  text is processed.
- Review the [privacy and security boundaries](./privacy) before using real
  documents.
- Keep the [troubleshooting guide](./troubleshooting) available while validating
  the first processing run.

---

<!-- Source: /docs/upgrading.md -->

# Upgrade to or within v3

The `tagvico_ai_data` volume is the upgrade boundary. It holds settings,
processing history, queues, and the local admin account. Keep it, back it up,
and change only the container image during a normal upgrade.

## Before upgrading

1. Read the [release notes](https://github.com/arturict/tagvico-ai/releases) and
   note any v3 migration warnings.
2. Keep **Review first** enabled if the release changes metadata behavior.
3. Stop Tagvico and back up its named volume:

```bash
docker compose stop tagvico-ai
docker run --rm \
  -v tagvico_ai_data:/source:ro \
  -v "$PWD":/backup \
  alpine tar czf /backup/tagvico-ai-data.tgz -C /source .
```

## Pull the pinned release

Update `image:` in `docker-compose.yml` to the exact release tag, then run:

```bash
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 tagvico-ai
curl http://localhost:8080/health
```

After signing in, confirm the displayed version, test the Paperless connection,
check `/api/health`, and open `/docs/` to confirm the bundled release
documentation is available. Process one non-sensitive document in **Review
first** before re-enabling Automatic mode.

Tagvico checkpoints SQLite and creates a pre-migration database backup before
schema upgrades. The external volume backup remains the safest rollback point.

The v3 Settings migration does not replace `data/.env`. Existing variable
names remain readable and compatible values are written back through the new
typed Settings API. `/settings` now redirects into the single Next.js settings
workspace; the removed EJS settings form is not a rollback or compatibility
surface.

Legacy bookmarks redirect into the task-oriented v3 information architecture:
`/dashboard` to `/automation`, `/history` to `/activity`, `/operations` to
`/automation/recovery`, and `/manual` to `/automation/manual`. `/review`
remains the clear approval destination. Their former EJS views and page-specific
browser scripts have been retired.

From 3.2 onward, `/automation` is labelled **Home**, `/documents` provides a
document-first history view, and `/tags` contains the dedicated duplicate-tag
review flow. These are navigation and presentation changes; existing history,
conversations, provider credentials, automation rules and recovery queues stay
in the same v3 data volume.

## Roll back

Stop the new container, restore the backup volume if the upgrade changed its
schema, pin the previous image tag, and start Compose again. Do not run two
Tagvico versions against the same volume at the same time.

::: danger v2 to v3
Treat a major-version upgrade as a maintenance window. Back up the volume,
read the v3 release notes, and allow the first container start to complete the
schema-v5 migration. It adds households, members, Action Cases, steps,
Companion sessions, and approval audit records. The visible application moves
to Next.js on port 3000 while the scanner runs as an internal process on port
3001; do not expose the internal port.
:::

---

<!-- Source: /docs/removing.md -->

# Remove Tagvico AI

Removing the container does not remove Paperless documents or metadata already
written to them. It also leaves the named data volume intact unless you
explicitly delete it.

## Keep data for a later reinstall

```bash
docker compose down
```

You can reinstall the same or a compatible v3 image later and attach the
existing `tagvico_ai_data` volume.

## Permanently delete local Tagvico data

First create a final backup if you may need settings, history, queues, or the
local admin account. Then remove the Compose stack and its named volume:

```bash
docker compose down --volumes
```

If you created the container with `docker run`:

```bash
docker rm -f tagvico-ai
docker volume rm tagvico_ai_data
```

::: danger This cannot be undone
Deleting `tagvico_ai_data` permanently removes Tagvico's local configuration,
credentials, history, review queue, snapshots, and admin account. It does not
revert metadata already written to Paperless-ngx. Use History restoration
before removal if you want to revert supported metadata snapshots.
:::

Action Center removal also deletes local cases, steps, Companion transcripts,
encrypted per-member tokens, and approval history. It does not remove
`tagvico/action` or Tagvico custom-field values already mirrored to Paperless;
remove those in Paperless separately if desired.

Finally, remove any Tagvico-specific API token from Paperless and revoke hosted
provider credentials that were dedicated to this installation.

---

<!-- Source: /docs/features.md -->

# Feature showcase

## Home and action workflows

Each Paperless document can have one Action Case with a title, summary,
priority, due date, assignee, and top-level state. A case may contain up to 100
steps for compound work such as reviewing a renewal, comparing an offer,
replying, and storing the confirmation. Solo workspaces upgrade to family
households when another member is added.

Household members are managed profiles for assignment, permissions, and Telegram;
they are not separate Tagvico web accounts. The local admin remains the web
console owner in v3.

Tagvico mirrors its case ID, state, next due date, assignee, and
`tagvico/action` tag to Paperless. It preserves unrelated tags and custom
fields. The complete checklist and audit trail remain in Tagvico.

![Tagvico v3.2 Home dashboard in the Paper and Pine application shell](/screenshots/home-paper-pine-v3.png)

This v3.2 capture comes from the representative release installation. It uses
generic document metadata and synthetic workspace labels. It exposes no
document contents, real account identifiers, credentials, or private endpoints.

## Household Companion and approvals

The Companion can count, search and read permitted Paperless documents, list
and inspect tags, list current actions, and prepare document, tag or Action
Case changes. The Tagvico harness owns the
session, narrow tool catalog, permissions, transcript, and approval records;
the selected model never receives shell or filesystem access.

Read tools run immediately. Write tools only create a durable proposal. An
owner or adult must approve it before the deterministic executor changes
Tagvico or Paperless. This includes creating, renaming, recoloring and deleting
tags as well as changing document metadata. The web chat uses AI SDK v6 streams and AI Elements.
Paperless research is intent-aware: a greeting stays a normal conversation,
library totals, including `doc://countdocuments`, use an exact count, and
document content is read only when the question requires it. Internal tool
markers are never shown as document citations. Each research card can reveal the safe search term,
matching document IDs, titles, dates, and result count without exposing OCR.
The right-hand research trail remains visible while tools run and groups safe
research evidence with any pending approvals. Conversations can be created,
searched, renamed, switched, and deleted from the chat workspace.
The composer model picker groups live models inside collapsible configured
providers, shows each provider identity, and offers only the reasoning efforts
advertised by the selected model.

![Tagvico v3.2 Ask Tagvico workspace with persistent conversations, approval boundary, composer, configured model and visible research trail](/screenshots/companion-paper-pine-v3.png)

The capture uses generic count queries and synthetic workspace labels to show
the research trail. No document contents, real account identifiers,
credentials, or provider payloads are visible.

## Operations at a glance

The dashboard shows processing progress, runner state, Paperless vocabulary
counts, recent activity, and token/cost-efficiency signals. **Scan now** starts
an on-demand pass without waiting for the schedule and reports how many
documents were eligible, applied, staged, skipped, or failed. Trigger tags are
optional: with no trigger tags, every new unprocessed document is eligible.

Home, Documents, Ask Tagvico, Organize tags, Activity, and Settings stay
inside one React application shell. Recovery, Manual processing, the Action
Center, and the conditional Review queue remain available from the workflows
that need them instead of competing as unexplained primary tabs. They share the same fixed,
collapsible navigation, Paper & Pine design tokens, responsive
tables, dialogs, high-contrast tags and controls, and inline feedback.
Page-shaped skeletons preserve the expected Home, Documents and Activity
layout while their live data is loading. Provider and model catalogs use the
same pattern instead of replacing the interface with loading text. The former EJS interfaces
for user-facing workflows are no longer part of the visible application.

## Controlled tagging

Choose whether the model may create open-ended tags or must stay within a
controlled vocabulary. Tag groups make a larger Paperless tag catalog easier
to manage, and a per-document maximum prevents noisy assignments. Four is the
default hard ceiling in both modes. The shared provider prompt asks for the
smallest useful set and avoids repeating language, correspondent, or document
type as tags.

## Review-first tag unification

The dedicated **Organize tags** workspace loads the current Paperless vocabulary and lets one configured,
live-discovered model propose likely duplicates. Suggestions are grouped
visually as several source tags becoming one canonical target, while every
source remains independently reviewable. The model only plans and explains; it
cannot write to Paperless. Every proposed merge is approved or rejected
separately. Approved work runs as two explicit, idempotent phases: move
document references to the chosen target, verify the result, then delete the
now-unused source tag.

![Tagvico v3.2 Organize tags workspace showing several source tags becoming one canonical target](/screenshots/tags-paper-pine-v3.png)

The representative capture uses generic duplicate tags and synthetic workspace
labels. It contains no document content, real account identifiers, credentials,
or endpoints.

## Prompt control

The maintained general prompt works across providers. **Custom filing prompt**
adds archive-specific terminology and preferences without replacing Tagvico's
contracts. **Advanced system prompt** can replace the general role
instructions, while prompt-injection protection, minimal-tagging rules and the
structured response contract remain mandatory.

## Review-first filing

In **Review first** mode, durable suggestions wait for approval. Inspect the
metadata diff, apply it, reject it, or leave it queued. Switching to Automatic
mode does not discard already queued suggestions.

In **Automatic** mode, Tagvico validates and writes enabled fields directly to
Paperless. Both modes support titles, tags, correspondents, document types,
dates, languages, custom fields, and optional owner assignment.

## History, restoration, and retry control

Every processing run records assigned metadata, field-level before/after
changes, custom fields, token usage, event source, and the original snapshot.
Single and bulk rescans use the current provider settings and deliberately
bypass the normal trigger-tag filter. Rescanning never deletes the audit trail
or the first restore snapshot.

**Restore original** replaces title, tags, correspondent, document type, date,
language, custom fields, and owner with the first state Tagvico captured. Use
**Validate history** to preview records whose Paperless documents no longer
exist, then clean up only those orphaned local records.

AI and OCR provider failures are attempted up to three times before moving into
**Permanently failed**. Resetting a failed document makes it eligible again.
Documents that must never be processed can instead be moved to the permanent
**Ignored documents** list with an optional reason. Un-ignoring one explicitly
queues a filter-bypassing rescan. Failed and Ignored counts remain visible in
the sidebar.

## OCR rescue

Documents with insufficient OCR can enter a durable rescue queue. Configure
Mistral OCR, an OpenAI-compatible vision endpoint, or Ollama vision. Local PDF
OCR limits rendered pages with `OCR_MAX_PAGES`; interrupted work returns to the
pending queue after restart. OCR retries use the same bounded three-attempt
discipline as document classification and cannot block the main scan queue
forever.

## In-product changelog

**What’s new** in the sidebar opens the release notes bundled with the running
instance. The top entry is the prepared v3.2.0 changelog, followed by the
complete v3.1 history. It stays marked as unreleased until the release image
and tag are actually published.

## Subscription-backed model access

The optional ChatGPT provider uses the bundled official Codex runtime for
inference and the stable `codex login --device-auth` flow. Its model picker is
fed by the signed-in account's live `model/list` response, including the
runtime default and each model's supported reasoning efforts. Curated names are
never presented as account availability. GitHub Copilot continues to use the
official Copilot SDK.

## Unified setup and settings

Setup and authenticated Settings now use the same React field, provider, and
validation components. Settings are divided into Paperless, AI models,
Automation, Tag library, Household, Security & privacy, and Diagnostics. The desktop navigation
is fixed and collapsible; narrow screens use horizontal, scrollable navigation
without a second legacy UI.

Provider configuration is generated from the central provider registry. The
model picker supports runtime discovery, search, provider grouping, local
favorites, capability badges, and keyboard-native controls.

![Tagvico v3.2 AI model settings with the provider registry and write-only credential boundary](/screenshots/ai-models-paper-pine-v3.png)

This capture shows provider names and product copy only. No API key, account
identifier, private endpoint, or signed-in profile is exposed.

The Ask Tagvico composer uses the same runtime catalog, but includes only
configured providers whose live discovery succeeded. It defaults to the
document-automation model and persists a validated per-session override.
Redacted activity cards make Paperless search, document reading, action lookup,
proposal preparation, and tool errors visible without exposing OCR, tokens, or
raw provider payloads.

## Optional Telegram family interface

An opt-in long-polling bot lets allowlisted people search the archive in natural
language, ask follow-up questions, download cited originals, and send a PDF or
photo into Paperless. Each Telegram ID maps to its own Paperless API token;
unknown users and group chats are ignored, and Paperless enforces every search,
download, upload, and metadata permission.

Conversation history for the legacy cited-search flow is bounded and held in memory only. `/clear` removes one
person's history, and a restart removes all histories. Uploads wait for the
Paperless consumption task, link the existing document when Paperless reports a
duplicate, and can optionally run Tagvico metadata classification. Automatic
metadata for bot uploads is a separate explicit opt-in because it bypasses the
web review queue.

When a Telegram allowlist entry also contains its Tagvico `householdId` and
`memberId`, `/actions` lists open cases and explicit action requests can create
approve/reject cards. Approval uses the same executor and audit trail as web.
Action Center linking is accepted only when the Telegram entry points at the
same Paperless instance as the main Tagvico configuration.

## Optional anonymous installation analytics

Installation analytics are off by default. Administrators can preview the
complete outbound heartbeat in Settings before opting in. Rotating daily and
monthly identifiers support active-installation counts without creating a
permanent installation profile; document content, metadata, URLs, identities,
keys, exact counts, and errors are never included. See [Privacy and
security](./privacy) for the complete field list and retention design.

---

<!-- Source: /docs/paperless-ai-tagging.md -->

# AI tagging and metadata for Paperless-ngx

Tagvico AI is a self-hosted companion for people who want more control over
automatic Paperless-ngx metadata. It reads OCR text through the Paperless API,
asks a local or hosted model for structured fields, validates the result, and
either queues a reviewable diff or writes approved fields back.

Every new unprocessed document is eligible by default. Trigger tags are an
optional opt-in filter, not a setup requirement. Leaving the trigger-tag field
empty scans all new documents on the configured schedule.

## When Tagvico is useful

- You want local AI tagging with Ollama, LM Studio, vLLM, or another compatible
  endpoint.
- You need titles, dates, correspondents, document types, languages, custom
  fields, or owner assignment in addition to tags.
- You want generated values constrained to an existing vocabulary.
- You want to inspect suggestions before changing Paperless documents.
- You need history, retry queues, metadata restoration, and visible token/cost
  signals around the classification workflow.

Paperless-ngx's own matching remains the simpler choice when deterministic
rules or its built-in learning already classify an archive reliably. Tagvico
adds value when documents vary, several fields must be extracted together, or
the operator wants to choose and evaluate a modern language model.

## Local and hosted privacy boundaries

With Ollama or another endpoint on your network, OCR text can remain on
infrastructure you control. Selecting OpenAI, OpenRouter, Ollama Cloud, OpenCode Go, or
another hosted service sends the document content required for classification
to that provider. Tagvico does not proxy document content through a
Tagvico-operated cloud.

Optional installation analytics are off by default and never contain document
content or metadata. See [Privacy and security](./privacy).

## A safe evaluation workflow

1. Install with an immutable image tag and back up the data volume.
2. Start in **Review first** with synthetic or non-sensitive documents.
3. Enable a small controlled tag vocabulary.
4. Keep the default maximum of four tags, then reduce the vocabulary if the
   model repeatedly selects overlapping concepts.
5. Add a Custom filing prompt only for archive-specific conventions; use the
   Advanced system prompt only when the maintained general prompt is
   insufficient.
6. Test 20–50 representative documents and record correctness per field.
7. Move only reliable fields or document types to Automatic mode.

Use the same test set when comparing providers. Count missing and incorrect
fields rather than judging the model's prose. The [provider guide](./providers)
contains cost-conscious starting points.

---

<!-- Source: /docs/providers.md -->

# Model provider overview

Provider choice determines where OCR text is processed, how credentials are
managed, which models are visible, and which cost modes are available. Validate
quality with representative documents before enabling Automatic writes. See
[Privacy and security](./privacy) before sending real document text to a hosted
service.

| Provider | Best for | Authentication / endpoint | Notes |
| --- | --- | --- | --- |
| OpenRouter | Curated cloud choice and easy model switching | API key | Recommended hosted starting point; requests are forwarded to the selected upstream provider. |
| Ollama | Fully local inference | Local `/api/chat` endpoint | Keeps processing on infrastructure you control; model quality and speed depend on hardware. |
| Ollama Cloud | Hosted Ollama models | API key | No local GPU required; document text leaves your network. |
| OpenAI direct | Native OpenAI models, Flex, and Batch | API key | Loads the API account's live `/v1/models` catalog; Flex and Batch remain model-dependent. |
| OpenCode Go | Subscription inference gateway | Go API key | OpenAI-compatible request path with provider-controlled limits. |
| GitHub Copilot | Account-scoped model discovery | OAuth device login or supported token | Uses the official SDK; every agent tool is denied. |
| CLI Proxy / OpenAI-compatible | CLIProxyAPI, LM Studio, LiteLLM, vLLM, custom gateways | `/v1` base URL and optional key | Uses Vercel AI SDK v6. Tagvico can load the endpoint's `/models` catalog or accept a model ID manually. |
| ChatGPT subscription | Optional private, low-volume model adapter | Stable Codex device login | Uses the bundled official Codex runtime and loads the signed-in account's live `model/list` catalog. It is not an API SLA. |

## Cost-conscious recommendations

These are starting points for document classification, where consistent
structured output matters more than maximum general-purpose reasoning. Test at
least 20–50 representative documents in **Review first** before deciding that a
model is good enough for Automatic mode.

| Provider | Recommended starting point | Why it is a good-value choice |
| --- | --- | --- |
| OpenRouter | **GPT-5.4 Mini** with low reasoning | Best general hosted default in Tagvico: reliable structured extraction without paying for a frontier-sized model. Try **GPT-5.4 Nano** or **Gemini 3.1 Flash Lite** for very clean, repetitive documents; avoid the free router for unattended production because the underlying model can change. |
| Ollama | **Qwen 3.5 4B** on modest hardware; **Gemma 4 12B** with 16 GB VRAM and enough system-RAM headroom | Qwen 4B was the best speed/quality default in Tagvico's July 2026 synthetic test. Gemma 12B scored higher but was roughly twice as slow and its prompt cache needed substantially more system RAM. |
| Ollama Cloud | **gpt-oss:20b-cloud** | Tagvico's default balances capability with a moderate hosted footprint and avoids buying or running a GPU. Recheck the cloud catalog and account limits before committing to it. |
| OpenAI direct | **GPT-5.4 Mini**; use **Batch** for non-urgent archives | Mini is the balanced default. **GPT-5.4 Nano** can reduce cost further for predictable invoices and statements. Batch is preferable when turnaround can wait; Flex is useful when supported and occasional slower availability is acceptable. |
| OpenCode Go | **DeepSeek V4 Flash** | This is Tagvico's budget-oriented default for the Go gateway. It suits classification-heavy workloads; confirm the current subscription allowance and gateway model catalog. |
| GitHub Copilot | **GPT-5.4 Mini** when the signed-in plan exposes it | It offers a strong quality/cost balance without a separate per-token key inside Tagvico. Prefer a model with the lowest billing multiplier that still passes your test set, because plan entitlements differ. |
| CLI Proxy / OpenAI-compatible | A subscription-backed model returned by CLIProxyAPI, or a **mini**, **flash**, or roughly **8B–20B instruct** model supported by your gateway | Compatible endpoints vary too much for one universal slug. Load the live catalog, start small, require reliable JSON, and increase model size only when the error rate justifies it. |
| ChatGPT subscription | The configured Codex model supported by the signed-in account | Suitable for one trusted, low-volume installation when subscription-backed inference is preferable. Model availability remains account-controlled and is not an API service guarantee. |

## Companion runtime architecture

The Companion uses Tagvico's own harness, inspired by the clean separation used
by OpenCode and Pi: credentials, model resolution, agent sessions, tools, and
approvals are independent layers. OpenCode Go, OpenRouter, OpenAI, and custom
OpenAI-compatible endpoints run through Vercel AI SDK v6. Codex is a separate
read-only adapter and cannot bypass Tagvico approvals.

### CLIProxyAPI and subscription models

Choose **CLI Proxy / Compatible**, enter the proxy's OpenAI-compatible `/v1`
URL and its API key, then select **Load models**. This integration uses
`@ai-sdk/openai-compatible`; the proxy may authenticate its own upstream CLI
accounts, but Tagvico never receives those upstream OAuth tokens. A model being
listed does not override the subscription's acceptable-use rules, quota, or
availability.

The built-in ChatGPT/Codex adapter is different: Tagvico starts the bundled
Codex app-server and reads its account-scoped `model/list` protocol. The picker
shows only the visible models returned by that runtime, in server order, along
with the reasoning levels each model advertises. If discovery fails, Tagvico
shows the failure; it never replaces the result with a hardcoded subscription
list. Luna, Terra, and Sol therefore appear only when the signed-in account
actually reports them.

### Reasoning and thinking effort

The effort control is model-scoped. It appears only when the selected runtime
reports reasoning options for that model, and it contains only the values from
that capability response. For example, one Codex model may expose `low` through
`max` while another account or model exposes a different set. Tagvico does not
invent a global list or claim unsupported efforts are available.

::: tip A practical selection rule
Start with the recommended mini or flash tier and low reasoning.
Measure incorrect or missing fields—not how impressive the prose sounds. Move
up one tier only when the cheaper model fails the same field or document type
repeatedly.
:::

### Ollama sizing notes

For a new modest setup, start with
[`qwen3.5:4b`](https://ollama.com/library/qwen3.5). Its tested Q4_K_M build is
about 3.4 GB. Try [`gemma4:12b`](https://ollama.com/library/gemma4) when a
7.6 GB model plus runtime and prompt-cache headroom fits comfortably. Do not
choose a model from download size alone: actual RAM or VRAM use is higher and
rises with context length.

Gemma 4, Qwen 3.5, Granite 4.1, and the tested Ornith build expose tool calling
through the local Ollama runtime. Tagvico reads Ollama's live
`/api/show` capabilities and only offers verified tool-capable Ollama models
in **Ask Tagvico**. Automatic filing uses structured JSON output instead, so a
model can remain available for metadata processing even when it is not suitable
for the Companion.

Reasoning-capable Ollama models may otherwise put schema output in the
`thinking` field and leave `response` empty. Tagvico disables thinking only for
structured document extraction, so Qwen 3.5 and Ornith return parseable metadata
while their tool capability remains available to Ask Tagvico.

Keep the context window only as large as your documents require, then compare
field accuracy and throughput on the same test set.

### July 2026 local Ollama benchmark

This is a Tagvico maintainer test, not an independent or universal model
ranking. It used Ollama 0.32.3 on an RTX 4070 Ti Super with 16 GB VRAM, an
Intel i7-14700F, 32 GB system RAM, Q4_K_M model builds, a 4,096-token context,
temperature 0, and one request at a time.

Eight installed models first processed the same 16 synthetic documents once.
The four highest-scoring candidates then repeated all documents three times.
The corpus covers German, English, French, and Italian invoices, contracts,
letters, a noisy receipt, missing information, typed custom fields, competing
dates, and a prompt-injection line inside OCR text. It used the same fixed
10-tag vocabulary for every model so tag precision was comparable. The automated metadata
score checks schema validity, a relevant title, language, document type,
correspondent, issue date, exact tag precision and recall, a four-tag limit,
custom fields, and injection resistance.

| Model | Download | Metadata score | Simple tool probes | Warm metadata median | Output tokens/s |
| --- | ---: | ---: | ---: | ---: | ---: |
| `gemma4:12b` | 7.6 GB | **0.88** | 1.00 | 3.04 s | 52.39 |
| `ornith:latest` | 5.6 GB | 0.85 | 1.00 | 1.80 s | 66.03 |
| `qwen3.5:4b` | 3.4 GB | 0.84 | 1.00 | **1.49 s** | 75.96 |
| `qwen3.5:9b` | 6.6 GB | 0.83 | 1.00 | 2.05 s | 70.39 |

The tool score is deliberately narrow: two prompts had to call
`search_documents` with the required query terms. It proves first-call tool
compatibility, not multi-turn Ask Tagvico quality, citations, or safe action
approval. All four candidates passed those probes in all three repetitions.

The practical default from this run is `qwen3.5:4b`. Gemma 12B produced the
highest metadata score, but Qwen 4B was much smaller and about twice as fast.
The 9B Qwen build did not beat 4B on this corpus. Ornith worked, including tool
calls, but remains an experimental coding-oriented model rather than the
default document recommendation.

One failed stress run also matters: after more than 40 consecutive Gemma 12B
requests, Ollama's prompt cache had grown to about 4.75 GB while the Windows
host had little free system RAM. Ollama returned HTTP 500 and restarted. The
complete rerun succeeded with zero failed probes after unloading the model
between repetitions. Keep real RAM headroom, not only VRAM headroom, and test
a representative batch before leaving a large archive unattended.

To reproduce the harness with models already installed:

```bash
npm run benchmark:ollama -- \
  --models qwen3.5:4b,qwen3.5:9b,gemma4:12b,ornith:latest \
  --repetitions 1
```

Raw responses and summaries are written to the ignored
`.local/benchmarks/ollama/` directory. They may contain document text supplied
to the harness, so inspect them before sharing.

For a CPU-only archive with thousands of existing documents, first process 50
representative documents and measure documents per hour. A full 3,000 to 4,000
document backlog can take a long time. Tagvico does not claim a universal
throughput number because CPU, OCR length, context size, and model choice all
change it substantially.

### What the controlled score does not hide

We also connected a real local Tagvico review-mode container to Paperless-ngx
and processed three synthetic PDFs with `qwen3.5:4b`. All three reached the
review queue, the prompt-injection line was ignored, and titles and
correspondents were useful. The run also exposed two real errors: one
electricity invoice received both `Energy` and `Utilities`, and its service
period was mistaken for the invoice date. A deliberately ambiguous invoice got
an untidy document type.

That is why the score above is not a promise about open tagging. For a new
archive, prefer **Restrict to existing tags**, keep **Review first** enabled,
and test a representative batch before automatic writes. Tagvico's default
prompt now explicitly rejects synonymous tags and distinguishes issue dates
from service, due, appointment, renewal, and coverage dates, but small local
models can still be wrong.

## Switching providers

Use **Settings → AI models**, complete the selected provider form, and test
the connection. With environment configuration, change `AI_PROVIDER`, keep the
provider-specific values in `data/.env`, and restart the container. Each
adapter has its own configuration namespace, so switching does not require
deleting the previous provider's values.

## Processing modes

- **Standard** processes each document immediately.
- **OpenAI Flex** reduces cost for supported OpenAI models in exchange for
  slower or less predictable availability.
- **Batch** submits asynchronous discounted work to OpenAI and may
  take up to 24 hours.

::: warning Catalogs change
Model names, pricing, quotas, subscription entitlements, and regional
availability are provider-controlled. Recheck the provider catalog before each
Tagvico release; it is not part of the compatibility contract.
:::

For current model identifiers and account entitlements, use the catalog shown
inside Tagvico after authentication. The concrete recommendations above are a
dated starting point, not an availability guarantee; providers may rename or
withdraw models between Tagvico releases.

---

<!-- Source: /docs/privacy.md -->

# Privacy and security

Tagvico reads OCR text and metadata from Paperless-ngx. A local Ollama or
compatible endpoint can keep that processing on infrastructure you control.
When you select a hosted provider, the document content required for
classification is sent to that provider under its terms.

## Deployment boundaries

- Provider secrets are stored in `data/.env` and are not written to the
  processing database.
- Settings APIs return only `configured: true/false` metadata for secrets.
  Existing keys and tokens are never sent back to React or rendered into HTML;
  leaving a secret field empty preserves its current value.
- Per-member Paperless tokens are encrypted with AES-256-GCM using a key derived
  from the installation secret. Plaintext tokens are never returned by the API.
- Back up the complete data volume, including the generated installation secret.
  Replacing that secret makes existing encrypted member tokens unreadable.
- Companion write proposals, decisions, and results are retained in the local
  SQLite audit trail. Provider prompts receive only the bounded context needed
  for the request.
- Companion activity cards are redacted on the server before streaming. They
  show the kind and status of Paperless research plus the user-authored search
  term and bounded document metadata. They never show OCR text, mutation
  payloads, model reasoning, provider errors, tokens, or complete tool results.
- The Tagvico harness exposes no host shell or filesystem tools. Paperless read
  and write capabilities are narrow, and every AI write requires approval.
- The container drops Linux capabilities and enables `no-new-privileges` in the
  recommended Compose configuration.
- Use a dedicated Paperless API token and only expose the Tagvico web port to
  trusted networks.
- Start with Review first and a controlled tag vocabulary.
- Back up the data volume before schema upgrades.

Tag-unification analysis sends tag names and coarse document-use counts to the
configured model provider. It does not send document OCR for that workflow.
The model can only propose pairs; deterministic, approval-gated server code
moves references and deletes a source tag after verifying that it is unused.

## Telegram bot boundary

The optional Telegram interface is not a local transport and Telegram bot chats
are not end-to-end encrypted. Questions, photos, PDFs, and any original sent
back through a download button pass through Telegram under its terms. Retrieved
Paperless OCR and the user's question are sent to the configured Tagvico model
provider. Choosing local Ollama or a local compatible endpoint keeps the model
step on infrastructure you control, but does not change the Telegram boundary.

Only explicitly allowlisted Telegram IDs are processed, only private chats are
accepted, and each ID has a separate Paperless API token. Paperless therefore
remains responsible for document visibility and mutation permissions. The
allowlist and tokens are configuration secrets; do not commit them. The bot has
no conversation database: bounded per-user history lives in process memory and
is removed by `/clear` or restart.

Answers derived from OCR can be incomplete or wrong. In particular, totals and
comparisons are assistant summaries rather than accounting-grade calculations;
use the cited-original buttons to verify them.

## Screenshot policy

Documentation screenshots must be inspected as final rendered pixels before
commit. They must not show API keys, tokens, real document text, personal names,
email addresses, account identifiers, private hostnames, or internal URLs.
Empty states, synthetic metadata, generic tags, and non-identifying aggregate
counts are acceptable.

The screenshots in this v3 guide use generic tag labels and sanitized document
state. They demonstrate product behavior without exposing source documents or
credentials.

## Optional installation analytics

Tagvico's anonymous installation analytics are disabled by default. You can
explicitly opt in from **Settings → Privacy → Anonymous installation
analytics**, preview the exact payload before sharing, send a test heartbeat,
or disable sharing again at any time.

When enabled, Tagvico sends one coarse heartbeat roughly every 24 hours. It
contains the application version, a broad processed-count
bucket, write mode, a broad provider category, three feature booleans, and
rotating daily/monthly identifiers. The locally generated secret used to derive
those identifiers never leaves the installation, and the monthly identifier
changes every month.

Tagvico never includes document text or metadata, names, emails, user or
document IDs, Paperless URLs, API keys, exact document counts, exact model
names, errors, hostnames, or IP-derived location in the payload. Receiver rows
expire after 62 days and only aggregate opted-in installation counts should be
published.

Set `TAGVICO_TELEMETRY_ENABLED=no` to enforce the default from the environment.
Self-hosted distributors may override `TAGVICO_TELEMETRY_ENDPOINT`; it must use
HTTPS. The complete policy and receiver source are available in
[`PRIVACY_POLICY.md`](https://github.com/arturict/tagvico-ai/blob/main/PRIVACY_POLICY.md)
and [`telemetry/`](https://github.com/arturict/tagvico-ai/tree/main/telemetry).

---

<!-- Source: /docs/troubleshooting.md -->

# Troubleshooting

Start with the container status, recent logs, and both health endpoints:

```bash
docker compose ps
docker compose logs --tail=200 tagvico-ai
curl --fail http://localhost:8080/health
curl --fail http://localhost:8080/api/health
```

`/health` verifies the Tagvico process and its database. `/api/health` also
reports the configured model adapter's health when the adapter exposes a
health check, and returns `503` on an explicit failure. An `unknown` provider
result is not a successful connection test; use the **Test connection** actions
in Settings to verify Paperless and the selected provider.

## Setup returns 403

Remote setup is disabled by default. When the browser is not running on the
same machine as Tagvico, temporarily set `ALLOW_REMOTE_SETUP=yes`, recreate the
container, and complete setup. Remove the setting afterward and recreate the
container again.

## Paperless connection fails

- Use the Paperless base URL without `/api`.
- Verify the API token in Paperless and use a dedicated token where possible.
- From a container, `localhost` refers to that container—not the Docker host.
  Use a shared Compose network and the Paperless service name, or a reachable
  host address.
- Test the exact URL from the Docker host before changing Tagvico settings.

## Provider health is degraded

Open **Settings → AI provider**, confirm the selected provider, and run its
connection test. Check the endpoint, model, credentials, account entitlement,
and provider status. Model catalogs and quotas are controlled by the provider
and may change independently of Tagvico.

For a local Ollama endpoint, confirm the model is pulled and that Ollama listens
on an address reachable from the Tagvico container. An endpoint bound only to
the host loopback interface is not normally reachable from another container.

## Documents are not processing

1. Check **Operations** for runner state, retries, terminal failures, or OCR
   rescue work.
2. Confirm the Paperless token can see the expected documents.
3. Use **Scan now** for an immediate pass.
4. Inspect **History** for the specific failure instead of repeatedly rescanning.

Keep **Review first** enabled while diagnosing write behavior. A suggestion that
is already queued remains reviewable when the processing mode changes.

## Upgrade does not start cleanly

Do not run two Tagvico versions against the same data volume. Stop the stack,
preserve the failed container logs, and follow the [rollback procedure](./upgrading#roll-back).
Restore the pre-upgrade volume backup when the new release migrated the database
and the previous image cannot read it.

## Get more help

When reporting a problem, include the Tagvico version, deployment method,
provider name, relevant sanitized log lines, and the failing health status.
Remove API keys, tokens, document text, personal data, account identifiers, and
private URLs before posting an issue in the
[GitHub issue tracker](https://github.com/arturict/tagvico-ai/issues).

---

<!-- Source: /docs/release-notes.md -->

# Release notes

## v3.2.0

Released 26 July 2026.

Tagvico 3.2 replaces the previous dark application and marketing surfaces with
one light **Paper & Pine** interface. The main navigation now follows concrete
jobs: Home, Documents, Ask Tagvico, Organize tags, Activity, and Settings.

Ask Tagvico is now a three-column research workspace. Conversations remain on
the left, the answer and configured-model composer stay in the centre, and a
live research trail shows every safe Paperless search, document read, source
count, and pending approval on the right.

Read tools can inspect documents and tags immediately. Document and tag
creates, edits and deletions remain inert until an owner or adult approves the
durable proposal. The configured-model picker is grouped by collapsible
provider and exposes model-specific reasoning levels.

Content requests such as read, inspect, open, and review now read the bounded
Paperless matches. GitHub Copilot receives the saved reasoning level, accidental
substring matches no longer start research, and conversations remain reachable
from a dedicated drawer on narrow screens.

Duplicate-tag cleanup has its own review workspace. Analysis is read-only, each
many-to-one mapping shows its document impact, and moving references remains a
separate operation from deleting the unused source.

Document chips, provider controls and model metadata now meet the light
interface's contrast targets. Home, Documents, Activity and live model catalogs
show their actual structure as skeletons while data is loading.

Upgrade by backing up `tagvico_ai_data`, pinning
`ghcr.io/arturict/tagvico-ai:3.2.0`, and recreating only the Tagvico container.
This remains a v3 upgrade. There is no v4 migration and no parallel beta-theme
preference.

## v3.1.2

Released 24 July 2026.

This focused Ask Tagvico hotfix removes embedding-only models from every chat
model picker. It covers common embedding names as well as colon- and
slash-delimited provider IDs such as `qwen3-embedding:4b`.

Upgrade by backing up `tagvico_ai_data`, pinning
`ghcr.io/arturict/tagvico-ai:3.1.2`, and recreating only the Tagvico container.
No settings or data migration is required.

## v3.1.1

- Unified Settings around eight supported runtimes with write-only credentials,
  live probes, scrollable model catalogs, and account authentication for
  ChatGPT subscription and GitHub Copilot.
- Added durable Ask Tagvico conversations, model choice, retry/copy/stop,
  privacy-safe tool activity, and intent-aware Paperless research.
- Made trigger tags optional, kept four tags as the default ceiling, and added
  clearer scan results, recovery queues, exact restore, and history cleanup.
- Added many-to-one duplicate-tag proposals, custom filing instructions, an
  advanced system prompt, and the in-product changelog.

## v3.1.0

- Moved every user-facing workflow into the same green React application shell.
- Reorganized navigation around Actions, Ask Tagvico, Automation, Activity, and
  Settings.
- Restored Paperless discovery, added approval-first tag unification, and
  bundled the matching versioned documentation at `/docs/`.

For complete technical details, see the repository
[CHANGELOG](https://github.com/arturict/tagvico-ai/blob/main/CHANGELOG.md) and
[GitHub releases](https://github.com/arturict/tagvico-ai/releases).

---