wealthos 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Volodymyr Melnyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# wealthos
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command-line tool for **[Wealthos](https://wealthos.cc)**, a personal
+wealth planning and forecasting app.
+
+## What is Wealthos?
+
+Wealthos helps you simulate life's big decisions before you make them (a
+house, a move, a career change, a sabbatical) and see where each one leaves
+you years out. It's built on your real balances across every bank and
+currency you hold: net worth, income and expenses, savings goals, dated plans
+and long-range forecasts.
+
+It comes in two editions:
+
+- **[Wealthos Cloud](https://wealthos.cc)**: web app and iOS app, with bank
+  connections and sync across devices.
+- **[Wealthos Local](https://wealthos.cc/local)**: a macOS app that keeps
+  everything as plain files in a folder you choose. No account, works
+  offline.
+
+Both expose your finances to AI assistants (Claude, ChatGPT, Cursor, Codex)
+through the [Wealthos MCP server](https://wealthos.cc/mcp).
+
+## What this package is for
+
+`wealthos` brings the same tools to a terminal, for scripts and for AI agents
+that work through a shell (Claude Code, Codex CLI, cron jobs). Output is JSON.
+
+- **Let an agent manage your finances.** Ask Claude Code "how much can I put
+  aside each month for a house in 2028?" and it can read your accounts, goals
+  and plans and run the forecast itself, instead of guessing at the
+  arithmetic.
+- **Check a purchase before you make it.** `affordability_check` returns a
+  verdict plus the trade-offs: a goal pushed back, investments to sell, a
+  safety buffer breached.
+- **Keep your finances as plain files.** A vault is a folder of YAML and
+  JSONL in the documented
+  [Open Wealth Format](https://wealthos.cc/open-wealth-format/v1/README.md),
+  so it works with `git`, backups and any editor. Create one, validate it,
+  and print the JSON Schema for any file type. The Wealthos desktop app opens
+  the same folder.
+- **Automate.** Log net worth from a cron job (`wealth_get`), add income
+  and expenses from a script, pipe any result into `jq`.
+- **Look up country money rules, no account needed.** Sourced, dated rules
+  for the cost of buying a home in 16 European countries, the Dutch 30%
+  ruling and German freelancer net income.
+
+Needs Node 20 or later.
+
+```sh
+npx wealthos --help
+```
+
+## A local vault
+
+```sh
+npx wealthos init ~/Documents/Wealthos --currency EUR
+npx wealthos call ~/Documents/Wealthos accounts_add name=Current type=bank balance=8200
+npx wealthos call ~/Documents/Wealthos wealth_get
+npx wealthos call ~/Documents/Wealthos affordability_check amount=1200 what="flight to Lisbon" --text
+npx wealthos doctor ~/Documents/Wealthos
+```
+
+If the Wealthos desktop app has the vault open, commands go through the app
+instead of opening the folder a second time.
+
+## Wealthos Cloud
+
+Pass the MCP server URL instead of a folder, with an API token from
+**Settings → Connect to AI tools via MCP** in the
+[Wealthos web app](https://wealthos.cc):
+
+```sh
+export WEALTHOS_TOKEN=wos_...
+npx wealthos tools https://mcp.wealthos.cc --text
+npx wealthos call https://mcp.wealthos.cc goals_list
+```
+
+## Country rules
+
+```sh
+npx wealthos rules                                    # every rule, with review status
+npx wealthos rules se.property_purchase_costs price=4500000 --text
+npx wealthos rules de.property_purchase_costs price=500000 region=berlin non_resident=true
+npx wealthos rules nl.expat_tax_regime gross_annual_salary=70000
+```
+
+Planning estimates, not tax or legal advice. Each rule lists its sources and
+when it was last checked.
+
+## Commands
+
+| Command | |
+|---|---|
+| `tools <target> [--text] [--schemas]` | List tools (JSON, or one line each) |
+| `call <target> <tool> [--args JSON] [key=value …] [--text]` | Call a tool. `key=value` values are read as JSON when they parse; dotted keys nest (`date.year=2027`) |
+| `schema [name]` | Open Wealth Format file types, or one JSON Schema |
+| `rules [id] [key=value …] [--country X] [--topic T] [--due] [--text]` | List, show or calculate a country rule |
+| `init <dir> [--email E] [--currency EUR]` | Create a vault |
+| `doctor <dir> [--clear-stale-lock]` | Validate every file in a vault; changes nothing |
+| `mcp-stdio <dir>` | Serve a vault to an MCP client over stdio |
+| `serve <dir>` | The local core the desktop app runs |
+
+`<target>` is a vault folder, or an `https://` MCP server URL with `--token` or
+`$WEALTHOS_TOKEN`.
+
+Exit codes: `0` success, `1` the tool reported a failure (its JSON is still
+printed), `2` bad usage or an unknown tool.
+
+## Links
+
+- [Wealthos](https://wealthos.cc): the app
+- [Wealthos Local](https://wealthos.cc/local): the macOS app for plain-file vaults
+- [Wealthos MCP server](https://wealthos.cc/mcp): connect Claude, ChatGPT and other assistants
+- [Open Wealth Format](https://wealthos.cc/open-wealth-format/v1/README.md): the vault file format
+- [Country rules](https://wealthos.cc/country-rules/v1/index.json): the rules library as JSON
+- [Issues](https://github.com/vamelnyk/wealthos-app/issues): report a problem or ask a question
+
+## License
+
+MIT