taylortrader 0.1.0__tar.gz

taylortrader-0.1.0/.env.example

@@ -0,0 +1,23 @@
+# Copy to .env (git-ignored) or, better, store these in the macOS Keychain:
+#   security add-generic-password -s taylortrader -a ALPACA_PAPER_KEY_ID -w
+# (-w with no value prompts for it, so the secret never lands in shell history)
+#
+# Lookup order for each name: environment variable, then .env, then Keychain (service "taylortrader").
+
+ALPACA_PAPER_KEY_ID=
+ALPACA_PAPER_SECRET_KEY=
+
+# Live keys are only read when config mode = "live" AND TAYLORTRADER_ALLOW_LIVE=1 (the dashboard sets it when you type GO LIVE).
+ALPACA_LIVE_KEY_ID=
+ALPACA_LIVE_SECRET_KEY=
+# TAYLORTRADER_ALLOW_LIVE=1
+
+# Alerts (optional)
+NTFY_TOPIC=
+EMAIL_PASSWORD=
+HEALTHCHECK_URL=
+
+# AI strategy (optional): the key for the provider set in [ai] in config.toml.
+# A local model (Ollama, LM Studio) needs no key: set [ai] endpoint instead.
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=

taylortrader-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: npm
+    directory: /dashboard
+    schedule:
+      interval: weekly

taylortrader-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - run: uv sync --locked
+      - run: uv run ruff check src tests
+      - run: uv run pytest -q
+      # The same secret scan the pre-commit hook runs, over every tracked file.
+      - run: uv run python -m taylortrader.secretscan
+
+  dashboard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+      - run: npm ci
+        working-directory: dashboard
+      - run: npx tsc --noEmit -p . && npm run build
+        working-directory: dashboard

taylortrader-0.1.0/.github/workflows/package.yml

@@ -0,0 +1,53 @@
+# Builds the package people install and tests it with the newest dependencies allowed, not uv.lock:
+# that's what a new user gets. Runs weekly so a breaking dependency update shows up here first.
+name: Package
+on:
+  schedule:
+    - cron: "17 13 * * 1"
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+      # No caches in the build that releases ship from: a poisoned cache can't reach a release.
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: false
+      # Also fails if the dashboard is missing or a file that must never ship got in.
+      - run: bash scripts/build-release.sh
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  test:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-latest]
+        python: ["3.12", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - run: uv venv --python ${{ matrix.python }} fresh
+      - run: uv pip install --python fresh --only-binary ":all:" dist/*.whl pytest httpx
+      - name: Tests run against the installed package
+        run: |
+          fresh/bin/python -c "import taylortrader, sys; assert 'site-packages' in taylortrader.__file__, taylortrader.__file__"
+          fresh/bin/python -m pytest -q

taylortrader-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,57 @@
+# Push a tag like v0.1.0 to publish. See CONTRIBUTING.md.
+name: Release
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+      - name: The tagged commit is on main
+        run: git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+      - name: The tag matches the version in the code
+        run: |
+          want="${GITHUB_REF_NAME#v}"
+          grep -qx "version = \"$want\"" pyproject.toml
+          grep -qx "__version__ = \"$want\"" src/taylortrader/__init__.py
+
+  package:
+    needs: version
+    uses: ./.github/workflows/package.yml
+
+  pypi:
+    needs: package
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Trusted Publishing: a short-lived login from GitHub, no stored token
+    steps:
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          enable-cache: false
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - run: uv publish --trusted-publishing always
+
+  github-release:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

taylortrader-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# --- Secrets: never commit ---
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+secrets/
+# Local config may hold account-specific settings; commit config.example.toml instead
+config.toml
+
+# --- Runtime data: market data cache, trade journal, logs ---
+var/
+*.db
+*.sqlite
+*.sqlite3
+*.parquet
+*.log
+cache/
+logs/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+
+# --- Dashboard ---
+node_modules/
+src/taylortrader/web/static/
+
+# --- OS / editors ---
+.DS_Store
+.idea/
+.vscode/
+
+# Local notes
+docs/journal/
+config.toml.bak
+config.tmp
+*.toml.tmp
+*.bak

taylortrader-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Bug reports, ideas and fixes are welcome. For anything large, open an issue first so we can agree on
+the approach before you spend time on it.
+
+## Setup
+
+```sh
+uv sync
+git config core.hooksPath scripts/githooks   # scans each commit for secrets
+uv run pytest -q
+uv run ruff check src tests
+```
+
+The hooks setting turns on the pre-commit secret scan, which catches keys before they get into a commit. Run the
+tests and the linter before you open a pull request; CI runs both.
+
+The dashboard is in `dashboard/` (`npm install`, then `npm run build`).
+
+## Ground rules
+
+- Safety first: every strategy buy has a stop-loss held at the broker, and nothing goes around the guardrails.
+- Never commit keys, account numbers or real trading records.
+- New behavior comes with tests. Anything that claims a strategy works needs the holdout and luck test.
+- Use your own paper account, never live, while developing.
+
+## Your contribution
+
+By submitting a contribution, you confirm it's your own work, and you agree that it's licensed under
+this project's [license](LICENSE.md) and that the project's owner may also use, relicense and sell it
+as part of TaylorTrader, including in paid versions. You keep the copyright to your work.
+
+## Releasing (maintainer)
+1. Set the same new version in `pyproject.toml` and `src/taylortrader/__init__.py`, and commit.
+2. `git tag v0.1.0 && git push origin v0.1.0`
+
+The Release workflow builds the package with the dashboard inside, installs it fresh, runs the tests,
+publishes to PyPI and creates a GitHub Release. PyPI versions can't be reused, so a bad release gets
+a new version number. Publishing uses PyPI Trusted Publishing, so there's no token to store.

taylortrader-0.1.0/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Brandon Taylor
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

taylortrader-0.1.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.5
+Name: taylortrader
+Version: 0.1.0
+Summary: A safety-first trading bot and scheduled long-term investing for Alpaca, with a local dashboard.
+Project-URL: Homepage, https://github.com/brandonmtaylor/taylor-trader
+Project-URL: Source, https://github.com/brandonmtaylor/taylor-trader
+Project-URL: Issues, https://github.com/brandonmtaylor/taylor-trader/issues
+Project-URL: Releases, https://github.com/brandonmtaylor/taylor-trader/releases
+Project-URL: Security, https://github.com/brandonmtaylor/taylor-trader/security/policy
+Author: Brandon Taylor
+License-Expression: FSL-1.1-ALv2
+License-File: LICENSE.md
+Keywords: alpaca,backtesting,investing,trading,trading-bot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.12
+Requires-Dist: alpaca-py==0.44.0
+Requires-Dist: anthropic<3,>=2.4
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: openai<4,>=1.50
+Requires-Dist: pandas<4,>=2.2
+Requires-Dist: pyarrow>=17
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: uvicorn<1,>=0.32
+Requires-Dist: yfinance==1.7.0
+Description-Content-Type: text/markdown
+
+# TaylorTrader
+
+**Set your strategies once, and let the bot watch the market for you.** TaylorTrader runs on your own
+computer and trades your [Alpaca](https://alpaca.markets) account automatically: it checks prices all
+day, buys and sells when your strategies say so, protects those trades with stop-losses, and tells you
+what it did. Mix short-term trading strategies, an AI that makes the calls, and long-term investing on
+a schedule. No staring at charts.
+
+![The TaylorTrader dashboard: account value, the bot's heartbeat, and growth of $100 against SPY](https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/overview.png)
+
+- **Runs on its own.** Once it's set up, it trades and invests by itself during market hours, checks
+  that every position is protected, and sends you a summary after each close. You step in only when
+  you want to.
+- **Talk to it from Claude.** Describe an idea in plain English and Claude turns it into rules,
+  backtests them against buying and holding, and adds the strategy when you say so. Ask how it's
+  doing, pause it, or move a stock to another strategy, all in conversation.
+- **An AI strategy that shows its work.** A language model decides buy, sell or hold, and explains
+  every call with its confidence, pros and cons. A report card grades each call against what happened next.
+- **Strategies without code.** Pick a built-in, or write rules like `close > ma_50 and rsi < 40`, and
+  backtest them in a click.
+- **Scheduled investing.** Put a set amount into a mix of funds every week or month, kept in balance,
+  and see first how that plan would have done over the last 10 years.
+- **On your phone.** Open the dashboard from your phone on your Wi-Fi, and get alerts for every buy,
+  sell and problem.
+- **Safety first.** Stop-losses held at Alpaca, limits on every order, and paper trading until you
+  choose otherwise.
+
+> **Not financial advice.** It trades on **paper** (simulated money) until you switch to live yourself.
+> Trading can lose money, and you're responsible for every order it places. Provided as is, with no
+> warranty (see the [license](https://github.com/brandonmtaylor/taylor-trader/blob/main/LICENSE.md)).
+
+**Status:** early, and in a paper-trading trial.
+
+## A quick tour
+
+**Ask Claude.** With the MCP server connected, for example:
+```text
+You:    Add a strategy for NVDA and AMD: buy when they pull back to the 50-day average with RSI
+        under 40, sell when RSI goes over 70.
+Claude: Writes the rules, backtests them on both stocks against buying and holding, shows you
+        the results, and adds the strategy once you say so.
+```
+
+**Every trade on the chart.** Each buy and sell, the stop-loss, and how much of the move each sell kept.
+Hover for any bar's price, and add moving averages, RSI and MACD.
+
+![The trade chart: hovering shows each bar's price; the 20-bar average, RSI and MACD are switched on, then the range changes to 3 months](https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/trade-chart.gif)
+
+**The AI's reasoning, call by call.**
+
+![AI decisions: each call with its confidence and a one-line reason](https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/ai-decisions.png)
+
+**What if you'd started 10 years ago?** Your investing plan, run on real past prices for each mix.
+
+![What if you'd started 10 years ago: $200 a month in each ready-made mix, run on real past prices](https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/what-if.png)
+
+<table>
+<tr>
+<td width="62%"><img alt="The Strategies page: strategy, symbols, bar size, position size, stop-loss and a one-click backtest" src="https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/strategies.png"></td>
+<td width="38%"><img alt="The dashboard on a phone, over the home Wi-Fi" src="https://raw.githubusercontent.com/brandonmtaylor/taylor-trader/main/docs/images/phone.png"></td>
+</tr>
+<tr>
+<td>Set up strategies and backtest them against buying and holding, without code.</td>
+<td>Open it from your phone on the same Wi-Fi, with a passcode.</td>
+</tr>
+</table>
+
+## Install
+**Platforms:** macOS is fully supported. Linux runs the dashboard, backtests and a foreground
+`taylortrader run`, with keys in a `.env` file; running in the background is set up for macOS only so
+far. Windows isn't supported.
+
+You need a free [Alpaca](https://app.alpaca.markets/signup) paper account (email only, no money).
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh   # once, if you don't have uv
+uv tool install taylortrader
+taylortrader                                      # opens the dashboard and walks you through setup
+```
+Setup takes about ten minutes: connect your Alpaca paper keys, pick a strategy and backtest it, check
+the safety limits, optionally add phone or email alerts, and start the bot in **dry run** (it decides
+and alerts, but places no orders). Then switch between Dry run, Paper and Live at the top of the page.
+
+Settings, the trade journal and logs live in `~/Library/Application Support/TaylorTrader` on macOS
+(`~/.local/share/taylortrader` on Linux). Update with `uv tool upgrade taylortrader`. The dashboard's
+**Guide** page explains everything in plain language.
+
+### Does my computer need to stay on?
+The bot only checks prices while your computer is awake, so a Mac that stays on (a Mac mini, or a
+laptop left plugged in and open) works best. On a laptop that sleeps:
+- Your stop-losses keep protecting open positions, because they're held at Alpaca, not on your computer.
+- Strategies on daily bars miss little; ones on 1- to 15-minute bars miss whatever happens while it sleeps.
+- The invest plan catches up: a buy that comes due while the laptop is asleep goes in when it wakes.
+- The watchdog may send a "not running" alert after the laptop wakes up.
+
+### From your phone
+`taylortrader wifi on` prints a passcode and the address to open (`http://<your-mac>.local:8787`).
+Each device signs in once and stays signed in for 30 days. Going live, changing API keys, and turning
+real-money buying back on after a pause only work on the Mac itself. It's plain http, so use it on a
+home network you trust; for anywhere else, put the Mac and phone on [Tailscale](https://tailscale.com).
+`wifi off` closes it again.
+
+## Talk to it from Claude (MCP)
+TaylorTrader includes an MCP server, so Claude Code or the Claude desktop app can check on the bot and
+adjust it: "how did the AI strategy do this week?", "move PLTR to macd_rsi", "backtest rsi_14 on NVDA
+hourly", or describe an idea and let Claude write the rules and test it. It's optional; the bot runs
+the same without it.
+
+- **Claude Code:** [install it](https://claude.com/claude-code), then run once:
+  ```bash
+  claude mcp add taylortrader --scope user -- taylortrader mcp
+  ```
+- **Claude desktop app:** Settings, then Developer, then Edit Config. Add this to the file (merge it if
+  it already has `mcpServers`) and reopen the app:
+  ```json
+  { "mcpServers": { "taylortrader": { "command": "/full/path/to/taylortrader", "args": ["mcp"] } } }
+  ```
+  The desktop app needs the full path (`which taylortrader` prints it).
+
+The dashboard's **Settings** page, under Claude, shows both filled in for your computer, with copy
+buttons. Then ask Claude "how's my trading bot doing?" to check it's connected. The dashboard doesn't
+need to be open.
+
+It uses the same rules as the dashboard: every change is checked, hard limits still apply, and changes
+are logged as coming from Claude. It can't go live, read or change keys, loosen limits on a live
+account, or turn buying back on after you pause it. Selling on a live account is off unless you turn
+on **Let Claude sell on a live account** in Settings, on your Mac.
+
+## AI strategy (experimental)
+`ai` asks a language model whether to buy, sell or hold, using your plain-English instructions, recent
+bars, indicators, and optionally the last 3 days of news. It works with:
+- **Your Claude subscription** through [Claude Code](https://claude.com/claude-code) (`claude -p`, with
+  no tools and none of your own settings). No API key; calls count toward your plan.
+- **The Claude API**, billed per call. The sturdier choice for running unattended.
+- **Any OpenAI-compatible API**: OpenAI, OpenRouter, Groq, or a free local model through Ollama or
+  LM Studio.
+
+The model only proposes. Position size, the stop-loss and every limit still apply, and an error, an
+off-menu answer or low confidence means hold. A daily call limit caps cost.
+
+It can't be backtested honestly, so the backtester refuses it: try it in dry run, then on paper.
+`taylortrader replay` tests it on past bars with each stock disguised, so the model can't recall what
+happened next.
+
+## Strategies
+Built-ins: `macd_rsi`, `macd`, `ma_20`, `rsi_14`, `ma_20_rsi`, `ma_200_rsi`, `ma_20_over_200_rsi`,
+`chaikin`, `pullback`. Each symbol belongs to one strategy, so
+it's always clear who manages a position.
+
+Or write your own with `rule`: a buy rule and a sell rule, like `close > ma_50 and rsi < 40` or
+`close > prev_high_20`. Rules can use price, volume, MACD and Chaikin, plus these at any length up to
+250 bars: `ma_N`, `ema_N`, `high_N`, `low_N`, `change_N` (percent), `avg_volume_N`, `rsi_N`, `atr_N`.
+Rules are parsed, never run as code.
+
+**Test an idea before trusting it.** The backtester always compares against buying and holding.
+`taylortrader search` goes further: it tunes on older data, then tests once on held-back data, and
+checks the result against random entries, so luck doesn't pass for skill.
+
+## Long-term investing
+An **invest plan** puts a set amount into a fixed mix of funds on a schedule (say $200 a month into US
+stocks, international stocks and bonds) and holds it.
+- Each contribution goes to whatever is furthest under its target first, so new money keeps the mix
+  balanced without selling. Fractional shares, so any amount splits exactly.
+- A period is never bought twice, even across restarts: each buy is recorded first and carries an
+  order id Alpaca won't accept twice.
+- It invests cash already in your Alpaca account; it can't move money from your bank.
+- Start in preview: it alerts what it would buy and places nothing. Buying for real asks you to type
+  the amount and schedule.
+
+The ready-made mixes are examples, not recommendations. What's built and what's planned is in the
+[investing proposal](https://github.com/brandonmtaylor/taylor-trader/blob/main/docs/proposals/investing.md).
+
+## Safety limits
+- **Stop-losses live at the broker.** Every strategy buy is a bracket order with a stop-loss held by
+  Alpaca, so the stop still works if TaylorTrader or your computer stops. A stop limits losses but can
+  fill below its price when a stock gaps down or moves fast. (The invest plan doesn't use stops: holding
+  through dips is its point.)
+- **Every order is checked** against position size, total exposure, daily loss, buys per day, stop
+  width, and a pause switch. Settings can tighten the built-in hard limits but never loosen them.
+  Sells are never blocked.
+- **It only manages what it bought.** Shares you already owned aren't touched, even if you add the
+  symbol to a strategy.
+- **Keys stay secret.** They live in the macOS Keychain (or a private `.env` file elsewhere), are
+  masked in logs, and the dashboard never shows them again. Config files with secret-looking values
+  are rejected.
+- **Real money needs two steps:** live keys that open an active account, and typing `GO LIVE` in the
+  dashboard on your Mac.
+- **It tells you when something's wrong:** a missing stop, a refused order, prices that stopped
+  arriving, a strategy that hasn't traded in two weeks, or the bot itself going quiet.
+
+## Command line
+Everything the dashboard does also works from a terminal:
+```bash
+taylortrader doctor                 # settings, credentials (found or missing), secret scan
+taylortrader strategies             # what you can pick
+taylortrader backtest VRT --strategy macd_rsi --timeframe 5Min --days 365
+taylortrader account                # read-only: positions, stops, positions it doesn't manage
+taylortrader alerts-test            # push and email test
+taylortrader run --dry-run --once   # one check: decides and alerts, places no orders
+taylortrader kill on                # pause new buys; sells and stops keep working
+taylortrader journal                # recent orders and the heartbeat
+taylortrader dashboard --background # keep the dashboard running (also --restart, --stop)
+taylortrader wifi on                # open it to your phone on the same Wi-Fi
+```
+Settings live in `config.toml` with no secrets in it;
+[config.example.toml](https://github.com/brandonmtaylor/taylor-trader/blob/main/config.example.toml)
+explains each one. The bot notices a saved change and restarts itself with it, and a file with a
+mistake in it is reported and ignored.
+
+**Price data:** `feed = "yahoo"` (the default) covers every exchange and is current, but unofficial;
+the bot switches to Alpaca IEX on its own if Yahoo fails or falls behind. `"iex"` is Alpaca, real
+time, one exchange. Backtests use Alpaca's full-market (SIP) history.
+
+## From source
+```bash
+git clone https://github.com/brandonmtaylor/taylor-trader && cd taylor-trader
+uv sync
+cd dashboard && npm install && npm run build && cd ..   # once, and after UI changes
+uv run taylortrader                                     # uses this folder for settings and data
+```
+In a checkout, put `uv run` in front of every command above. See
+[CONTRIBUTING.md](https://github.com/brandonmtaylor/taylor-trader/blob/main/CONTRIBUTING.md) to help
+out, and [SECURITY.md](https://github.com/brandonmtaylor/taylor-trader/blob/main/SECURITY.md) to report
+a problem privately.
+
+## License
+Source-available under the [Functional Source License 1.1, Apache 2.0 future
+license](https://github.com/brandonmtaylor/taylor-trader/blob/main/LICENSE.md) (FSL-1.1-ALv2). Use it,
+change it, run it for yourself, learn from it, contribute: all free. What it doesn't allow is selling
+it, or a product built from it that does the same job, in competition with TaylorTrader. Each version
+becomes plain Apache 2.0 two years after it's released.