{
  "markdown": "# Ownly\n\n[![Obsidian Plugin](https://img.shields.io/badge/Obsidian-Plugin-blue?logo=obsidian)](https://obsidian.md/plugins?id=ownly)\n[![Web App](https://img.shields.io/badge/Web-Open_Ownly-111827?logo=googlechrome&logoColor=white)](https://liuh886.github.io/ownly/app/)\n[![PWA](https://img.shields.io/badge/PWA-Installable-0f766e?logo=pwa&logoColor=white)](https://liuh886.github.io/ownly/app/)\n[![Status](https://img.shields.io/badge/status-stable_1.x-brightgreen.svg)](CHANGELOG.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F7WYJ6B)\n\n> **Own less, Live more, Decide better.**\n\n[中文文档](README.zh.md)\n\n**A local-first ownership memory and decision ledger.**\n\nOwnly helps you record what you own, what it costs, how you used it, and what you learned. Personal data stays in an **Ownly data folder** as plain Markdown with YAML frontmatter.\n\n> **Ownly doesn't host your data. You choose where your files live.**\n\nThe Ownly data folder can live in a normal local directory or inside a local folder synchronized by a personal cloud provider you control. Obsidian is useful for inspecting the Markdown, but it is **not required** for the hosted Web app, installed PWA, Agent CLI, or local MCP server.\n\n## Open Ownly\n\n- **[Explore the product page](https://liuh886.github.io/ownly/)**\n- **[See the embedded product preview](https://liuh886.github.io/ownly/#preview)**\n- **[Open the Web app / PWA](https://liuh886.github.io/ownly/app/)**\n\n| Entry point | Obsidian required? | Local process required? | Best for |\n|---|---:|---:|---|\n| GitHub Pages Web app | No | No | Immediate use in a supported desktop browser |\n| Installed PWA | No | No | A standalone app window with offline application-shell startup |\n| Obsidian plugin | Yes | No | Native Vault integration and direct Markdown work |\n| Agent CLI | No | Yes | Deterministic scripting and validated local mutations |\n| Local MCP | No | Yes | Bounded reads plus opt-in, preview-before-commit maintenance for compatible agents |\n\nThe Web app and PWA are the same browser runtime. Installation changes the launch experience, not the data model. The product homepage itself is not a PWA surface.\n\n## First use: choose where your data lives\n\nWhen Ownly starts without an existing folder permission, choose a storage location and then create new data or open an existing Ownly data folder.\n\n### On this device\n\nChoose a normal local filesystem folder. Ownly reads and writes that folder directly. Nothing is synchronized unless you configure synchronization outside Ownly.\n\n### In your personal cloud folder\n\nChoose a local folder already synchronized by Dropbox, Google Drive, OneDrive, iCloud Drive, or another provider you control.\n\nOwnly still works with normal local files. It does not use provider APIs, OAuth, provider credentials, an Ownly cloud mirror, or a separate remote filesystem. Your provider handles synchronization under its own privacy and security policies.\n\nKeep the folder available offline when the provider supports online-only placeholders, and use **one sync provider per Ownly data folder** to reduce conflicting copies.\n\n### Create new data\n\nSelect a parent location such as `Documents`, an Obsidian Vault root, a local personal-cloud folder, or an empty folder already named `Ownly`.\n\nOwnly initializes:\n\n```text\nOwnly/\n  Objects/\n  Accounts/\n  Snapshots/\n  Reviews/\n  Trips/\n  Trip Places/\n  Trip Visits/\n  Trip Legs/\n  Trip Expenses/\n  Logs/\n    Object Experiences/\n  Archive/\n    Objects/\n    Accounts/\n    Snapshots/\n    Reviews/\n    Object Logs/\n```\n\nIf the selected folder is already named `Ownly`, Ownly uses it directly and does not create `Ownly/Ownly`.\n\n### Open existing data\n\nSelect any supported filesystem location:\n\n- an initialized Ownly data root containing `Objects/`;\n- an empty or initialized folder named `Ownly`;\n- an Obsidian Vault containing an `Ownly/` child folder;\n- an Obsidian Vault using the plugin's configured Ownly data folder;\n- any of the above inside a local folder synchronized by the user's own provider.\n\nThe browser asks for explicit read/write permission. Personal Markdown files are not uploaded to GitHub Pages and are not copied into the PWA service-worker cache. If the selected folder is synchronized by a third-party provider, that provider may upload and synchronize those files independently of Ownly.\n\nThe hosted Web/PWA runtime uses Google Analytics 4 measurement ID `G-KXXVS33FQ2` for product adoption and can also load Cloudflare Web Analytics for aggregate traffic and Web Vitals when `NEXT_PUBLIC_CLOUDFLARE_WEB_ANALYTICS_TOKEN` is configured at build time. Ownly custom analytics events never include Markdown contents, local file names, form values, object records, reviews, account snapshots, selected-folder data, local paths, inferred provider names, or MCP tool results. The Obsidian plugin, Agent CLI and MCP runtime do not load either web analytics provider.\n\n## Recommended storage\n\nStandalone local use:\n\n```text\n<My local folder>/\n  Ownly/\n    Objects/\n    Accounts/\n    Snapshots/\n    Reviews/\n    Trips/\n    Trip Places/\n    Trip Visits/\n    Trip Legs/\n    Trip Expenses/\n    Logs/\n    Archive/\n```\n\nInside an Obsidian Vault:\n\n```text\n<My Obsidian Vault>/\n  Ownly/\n    Objects/\n    Accounts/\n    Snapshots/\n    Reviews/\n    Trips/\n    Trip Places/\n    Trip Visits/\n    Trip Legs/\n    Trip Expenses/\n    Logs/\n    Archive/\n```\n\nInside a personal cloud-synced local folder:\n\n```text\n<My Dropbox / Google Drive / OneDrive / iCloud Drive folder>/\n  Ownly/\n    Objects/\n    Accounts/\n    Snapshots/\n    Reviews/\n    Trips/\n    Trip Places/\n    Trip Visits/\n    Trip Legs/\n    Trip Expenses/\n    Logs/\n    Archive/\n```\n\nAll three layouts use the same Ownly data model. The personal-cloud option does not introduce a second storage backend; the external provider synchronizes the normal filesystem folder.\n\n## Product principles\n\n- **User-controlled storage** — Ownly does not host your personal ledger. You choose where the filesystem folder lives.\n- **Local by default** — no required cloud account, hosted database, provider OAuth, or mandatory synchronization.\n- **Markdown native** — records remain portable and human-readable.\n- **Decision led** — observe, acquire or pass, use, exit, and review.\n- **Recoverable mutations** — archive and restore are distinct from permanent deletion.\n- **One data model** — Web, PWA, Obsidian, CLI and MCP operate on the same schemas and directory structure.\n- **Fact ready** — scripts and external AI agents can consume deterministic data contracts; Ownly itself is not an AI assistant.\n\n## What Ownly tracks\n\n| Record | Purpose |\n|---|---|\n| Physical item | Purchase, use, cost, condition, retirement, transfer, or discard lifecycle |\n| Recurring cost | Subscription or other repeating obligation, billing cycle, status, and annualized cost |\n| One-time experience | Plan, budget, actual cost, location, completion, and review |\n| Snapshot | Point-in-time net-worth and account-balance facts |\n| Review | Structured post-use, post-exit, monthly, or annual reflection |\n| Object experience log | Append-only usage, issue, maintenance, regret, lesson, comparison, or exit event |\n\n## Fact-ready Agent CLI\n\nOwnly exposes deterministic JSON read/write commands for scripts and external agents. It does not include model APIs, embeddings, AI chat, or generated recommendations.\n\n```bash\nexport OWNLY_VAULT=/path/to/location-containing-Ownly\n\n# Recommended (wyqd remains for backward compatibility)\nnpm run --silent ownly -- object list --json\n# Legacy alias\nnpm run --silent wyqd -- object list --json\nnpm run --silent wyqd -- object get --id <id> --json\nnpm run --silent wyqd -- object history --id <id> --json\nnpm run --silent wyqd -- object review-needed --json\nnpm run --silent wyqd -- recurring list --active --json\nnpm run --silent wyqd -- summary --json\n```\n\nSee:\n\n- [Agent CLI Contract](docs/AGENT_CLI_CONTRACT.md)\n- [Agent CLI Guide](docs/AGENT_CLI_GUIDE.md)\n- [Data Model](docs/DATA_MODEL.md)\n\nThe CLI data location may point to an Obsidian Vault or another filesystem location containing the Ownly data folder, including a user-controlled synchronized local folder.\n\n## Agent / MCP\n\nOwnly also exposes a **local-first MCP server** for Codex, Claude Code and other MCP clients that can start a local STDIO process. It is read-only by default; persistent mutations require explicit startup permission plus a separate preview and commit call.\n\nThe MCP server is an adapter over the same validated Ownly data model. It does not create a second database, hosted mirror or embedded AI assistant.\n\nThe MCP tool surface covers:\n\n- data summary and Doctor health checks;\n- object search and bounded object facts;\n- object history with reviews and append-only experience logs;\n- active recurring costs;\n- upcoming subscription renewals;\n- recurring costs grouped by payment account with currencies kept separate;\n- deterministic review-needed records.\n- opt-in creation and updates, lifecycle changes, append-only logs, reviews, snapshots, and recoverable archive/restore;\n- short-lived before/after previews, pre-write backups, stale-write conflict detection, and idempotent commits.\n\nThe source-of-truth stays in the user-selected Ownly data folder. Facts returned by an MCP tool can enter the connected external agent's context, so Ownly does not claim that every selected fact remains on-device during an agent session.\n\nThe publish-ready MCP package lives in [`packages/mcp`](packages/mcp). See the [Ownly MCP Guide](docs/MCP.md) for Codex and Claude Code setup, privacy boundaries and example prompts.\n\n## Current runtime status\n\n| Area | Status |\n|---|---|\n| Product homepage | Static bilingual product explanation with an embedded interactive preview |\n| Hosted Web app | Static GitHub Pages runtime with user-selected filesystem access |\n| Installed PWA | App-route-only install surface, standalone launch and cached app shell |\n| Obsidian plugin | Native Vault interface over the shared Ownly data model |\n| Agent CLI | Stable, strict-typed fact-ready JSON contract |\n| Local MCP | Read-only by default; opt-in two-phase writes over the canonical Ownly evidence store |\n| Data storage | Plain Markdown + YAML frontmatter in a user-controlled filesystem folder |\n| Mutation safety | Validation, preview/commit confirmation, atomic writes, safety backups, audit logs, conflict detection, archive/restore, and CI contracts |\n\nCurrent validation and known coverage gaps are documented in [Quality Baseline](docs/QUALITY_BASELINE.md).\n\n## Browser support\n\nDirect folder access uses the File System Access API.\n\n- Recommended: current desktop Chrome or Microsoft Edge.\n- Unsupported browsers can view the product page and embedded preview but cannot connect a real Ownly data folder.\n- Mobile direct-folder access is not a production target.\n- Browser permission may need to be renewed after restart or permission reset.\n- A personal cloud folder must be exposed by its provider as a usable local filesystem folder; Ownly does not provide a remote-drive API fallback.\n\nSee [Web Runtime](docs/WEB_RUNTIME.md) for privacy boundaries, PWA behavior, and deployment details.\n\n## Obsidian plugin\n\nInstall from Obsidian Community Plugins:\n\n👉 **[Install Ownly](https://obsidian.md/plugins?id=ownly)**\n\nThe plugin is optional for Web/PWA users. Use the term **Obsidian Vault** only for a real Vault or the Obsidian runtime; the cross-runtime storage term is **Ownly data folder**.\n\n## Data health\n\nOwnly includes deterministic Doctor checks for issues such as:\n\n- duplicate IDs;\n- unsupported schema versions;\n- invalid costs or dates;\n- missing object/review references;\n- stale snapshots;\n- missing data directories.\n\nThese checks operate on Ownly facts and filesystem accessibility. Doctor does not inspect cloud-provider accounts or use AI.\n\n## Documentation\n\n- [User Guide](docs/USER_GUIDE.md)\n- [Planner Guide](docs/PLANNER.md)\n- [Capture Sync Boundary](docs/CAPTURE_SYNC_BOUNDARY.md)\n- [Web Runtime](docs/WEB_RUNTIME.md)\n- [Terminology Contract](docs/TERMINOLOGY.md)\n- [Product Governance](docs/PRODUCT_GOVERNANCE.md)\n- [Quality Baseline](docs/QUALITY_BASELINE.md)\n- [Agent CLI Contract](docs/AGENT_CLI_CONTRACT.md)\n- [Agent CLI Guide](docs/AGENT_CLI_GUIDE.md)\n- [Agent / MCP Guide](docs/MCP.md)\n- [Data Model](docs/DATA_MODEL.md)\n- [Troubleshooting](docs/TROUBLESHOOTING.md)\n- [Release Checklist](docs/RELEASE_CHECKLIST.md)\n\n## Development\n\n```bash\nnpm ci\nnpm run validate\nnpm run test\nnpm run test:e2e:data\nnpm run test:mcp\nnpm run wyqd -- --vault <path> object list --json\n```\n\nMCP package validation additionally runs only for MCP-specific changes:\n\n```bash\nnpm install --prefix packages/mcp --ignore-scripts --no-audit --no-fund\nnpm run build --prefix packages/mcp\nnode packages/mcp/dist/index.js --help\n(cd packages/mcp && npm pack --dry-run)\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE). Ownly does not host personal ledger data. A user-selected filesystem-sync provider or external MCP client may process data under its own privacy and security policies. Hosted Web/PWA may use GA4 for limited product-adoption events and Cloudflare Web Analytics for aggregate traffic and Web Vitals; the Obsidian plugin, CLI and MCP runtime do not load either analytics provider.\n",
  "bytes": 13357,
  "sha": "fe4e1c98094146905ee2c2f75ad4a91016e13646f84a4bbc95af2874e34df31d",
  "repo_slug": "liuh886/ownly",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_liuh886_ownly_666a039a/readme"
}