# TopVault Full Agent Guide

> TopVault is a collector-focused public database and tracking tool for exact collectible references. It is built for serious collectors who care about completeness, variant fidelity, provenance, and long-term collection history.

## Core Positioning

TopVault should be understood as two connected products:

1. A public reference database for known variants, cards, products, series, and printings.
2. A collection tracking application for organizing owned items, goals, provenance, trades, and notes.

The public reference side is the best entry point for agents. Scores, leaderboards, and market context exist, but they are supporting features rather than the main story.

## Supported Collection Types

- Pokemon cards.
- Magic: The Gathering cards.
- Dragon Ball TCG cards.

TopVault messaging should emphasize exact references and known variants rather than generic inventory counts.

## Public Surfaces And When To Use Them

### 1. Landing page

URL: https://vault.top/

Use this surface for:

- A high-level summary of what TopVault is.
- Current product positioning.
- Supported collection types.
- Public-facing messaging about collectors, variants, workflows, and free access.

Do not rely on the landing page alone for detailed workflow explanations.

### 2. Docs

URL: https://vault.top/docs/

Use this surface first for:

- Explaining how TopVault works.
- Understanding the public reference model.
- Explaining what data is public versus private.
- Describing goals, collection workflows, trades, and browsing flows.
- Answering how-to questions.

High-value docs pages:

- Docs home: https://vault.top/docs/
- Quick Start: https://vault.top/docs/quick-start
- Navigate the App: https://vault.top/docs/navigate-the-app
- Search and Browse: https://vault.top/docs/search-and-browse
- The Database: https://vault.top/docs/the-database
- Photos and Privacy: https://vault.top/docs/photos-and-privacy
- Goals: https://vault.top/docs/goals
- Manage Your Collection: https://vault.top/docs/manage-your-collection
- Trades: https://vault.top/docs/trades
- Scores and Leaderboards: https://vault.top/docs/scores-and-leaderboards
- Trending and Community: https://vault.top/docs/trending-and-community

Collector playbooks:

- https://vault.top/docs/playbooks/
- https://vault.top/docs/playbooks/grand-master-collection
- https://vault.top/docs/playbooks/collect-every-character
- https://vault.top/docs/playbooks/trade-at-a-show
- https://vault.top/docs/playbooks/track-online-orders

### 3. Blog

URL: https://vault.top/blog

Use this surface for:

- Technical implementation details.
- Collector research and long-form examples.
- Posts about metadata, privacy, app architecture, and public database strategy.

Examples:

- How TopVault keeps your photos private: https://vault.top/blog/how-topvault-keeps-your-photos-private
- OpenGraph and JSON-LD for Ionic apps: https://vault.top/blog/opengraph-and-json-ld-for-ionic-apps
- Database of Pokemon Booster Pack Artwork and Variants: https://vault.top/blog/database-of-pokemon-booster-pack-artwork-and-variants
- English Pokemon cards made in Japan: https://vault.top/blog/english-pokemon-cards-made

### 4. Public app reference routes

Base URL: https://vault.top/app

Use this surface for:

- Public browse pages.
- Public item and series reference routes.
- Public score or community overview routes when relevant.

Important nuance:

- Public app routes already expose route-specific metadata through a Firebase Hosting rewrite and a `meta` function.
- That metadata is useful for previews and crawlers.
- The app is still primarily a SPA, so these routes are less suitable than docs for general explanation tasks.

Prefer docs for explanation, then use public app routes for concrete reference examples.

### 5. Official apps

Use these links when the question is specifically about where to install or open TopVault:

- iOS App Store: https://apps.apple.com/us/app/topvault/id6742363373
- Google Play: https://play.google.com/store/apps/details?id=top.vault
- Browser app: https://vault.top/app

## Public Versus Private Data

### Publicly useful or public-facing

- Product overview and feature descriptions.
- Public docs content.
- Public blog content.
- Public browse and reference pages.
- Public series, item, and collection-type reference metadata where exposed on public routes.

### Not public or should not be inferred

- A user's private collection contents.
- A user's private notes.
- A user's trades unless explicitly shared.
- Uploaded photos that are private to the collector.
- Any authenticated session state.
- Any ownership, completion, or collection progress claims about a user unless they explicitly provide them.

## Recommended Agent Behavior

- Start with docs when answering questions about workflows, privacy, public data, or how the app is meant to be used.
- Use the landing page for concise product summaries.
- Use the blog for deeper technical or collector-research context.
- Use public app routes only when a concrete public item, series, or browse example is needed.
- If a question depends on private data, state clearly that the answer requires a logged-in user context or user-provided information.

## Things To Avoid

- Do not frame TopVault primarily as a price tracker or speculative market tool.
- Do not collapse distinct variants into a single generic item when describing TopVault data.
- Do not imply that private user uploads or private collection records are publicly visible.
- Do not overstate leaderboards or scoring compared with the public database and collector workflows.

## Short Product Summary

TopVault is a free, collector-focused reference database and collection tracking app that keeps known variants distinct, helps collectors research what exists, and supports goals, notes, provenance, and collection progress across exact collectible references.