Write a proper project README with the brand mark
Replaces the minimal AMO-source-submission README with a full project overview: logo, what Osias actually does, how it works, shipped features, getting started, project structure, and contributing — folding the existing build-instructions content in rather than dropping it, since AMO's source review still depends on it. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HoMzqFw3d93hG6c9xB4thU
This commit is contained in:
@@ -1,42 +1,128 @@
|
|||||||
# Osias — copilot
|
<p align="center">
|
||||||
|
<img src="public/icon/osias-icon-512.png" width="96" height="96" alt="Osias" />
|
||||||
|
</p>
|
||||||
|
|
||||||
Your blockchain-powered trading companion. This is the open-source browser extension
|
<h1 align="center">Osias</h1>
|
||||||
frontend (Apache License 2.0). See [`CLAUDE.md`](CLAUDE.md) for full architecture and
|
|
||||||
protocol documentation.
|
|
||||||
|
|
||||||
## Build instructions
|
<p align="center">
|
||||||
|
A blockchain-powered trading companion for the emotional side of trading.
|
||||||
|
</p>
|
||||||
|
|
||||||
Built with [WXT](https://wxt.dev) (Vite-based). To reproduce the exact `.output/firefox-mv3`
|
<p align="center">
|
||||||
bundle submitted to addons.mozilla.org from source:
|
<a href="https://osias.trade">Website</a> ·
|
||||||
|
<a href="https://osias.trade/privacy">Privacy Policy</a> ·
|
||||||
|
<a href="LICENSE">Apache 2.0 License</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## About
|
||||||
|
|
||||||
|
Osias isn't a trading bot or a P&L tracker. Trades are already visible on-chain, so
|
||||||
|
instead of asking you to log anything, Osias watches your connected Solana wallet in
|
||||||
|
real time and steps in only when it detects loss-driven trading — a single bad trade or
|
||||||
|
a losing streak past a threshold you control — by locking new buy actions on supported
|
||||||
|
trading sites until the moment passes.
|
||||||
|
|
||||||
|
This repository is the **open-source browser extension frontend** (Apache 2.0). The
|
||||||
|
backend that makes the actual lock/unlock decisions — auth, wallet/RPC listening,
|
||||||
|
realized-PnL tracking — is a separate, private service; this extension talks to it over
|
||||||
|
a documented WebSocket protocol and never contains trading logic of its own.
|
||||||
|
|
||||||
|
## How it works
|
||||||
|
|
||||||
|
1. **Connect your wallet** — real Phantom sign-in via message signing. Your seed phrase
|
||||||
|
and private key never touch the extension.
|
||||||
|
2. **Osias watches** — a live Solana subscription tracks your realized P&L in the
|
||||||
|
background while you're connected, nothing more.
|
||||||
|
3. **Buying locks** — cross your configured threshold and new buy actions visually
|
||||||
|
disable on the page. Sell and manage actions are never touched.
|
||||||
|
4. **The moment passes** — the lock auto-unlocks after a configurable cooldown, or you
|
||||||
|
can unlock manually with an explicit confirmation.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- Real Phantom wallet authentication — connect, sign, sign out, switch accounts
|
||||||
|
- Real-time lockout enforcement on [axiom.trade](https://axiom.trade), with a
|
||||||
|
non-destructive blur + lock-icon visual treatment
|
||||||
|
- Two configurable circuit breakers (single-trade and losing-streak loss thresholds)
|
||||||
|
plus a configurable auto-unlock cooldown, all tunable from the extension popup
|
||||||
|
- Live backend connection status, so a dropped connection is never silently mistaken
|
||||||
|
for "unlocked"
|
||||||
|
- Built for Firefox/Zen and Chromium (Manifest V3) from one codebase
|
||||||
|
|
||||||
|
See [`CLAUDE.md`](CLAUDE.md) for the full architecture — including the site-adapter /
|
||||||
|
intervention-strategy split that new sites and lock treatments build on, and the
|
||||||
|
complete WebSocket wire protocol shared with the backend.
|
||||||
|
|
||||||
|
## Getting started
|
||||||
|
|
||||||
|
Scaffolded with [WXT](https://wxt.dev) (Vite-based, TypeScript, React,
|
||||||
|
`webextension-polyfill`). Package manager: npm.
|
||||||
|
|
||||||
|
```sh
|
||||||
|
npm install # also runs `wxt prepare` via postinstall
|
||||||
|
npm run dev:firefox # dev build + watch, auto-opens a temporary Firefox/Zen profile
|
||||||
|
```
|
||||||
|
|
||||||
|
Other commands:
|
||||||
|
|
||||||
|
| Command | What it does |
|
||||||
|
| ----------------------- | ---------------------------------------------------------- |
|
||||||
|
| `npm run dev` | Dev build + watch, targets Chromium by default |
|
||||||
|
| `npm run dev:firefox` | Dev build + watch targeting Firefox (use this for Zen) |
|
||||||
|
| `npm run build:firefox` | Production build → `.output/firefox-mv3/` |
|
||||||
|
| `npm run zip:firefox` | Production build packaged as a `.zip` for store upload |
|
||||||
|
| `npm run compile` | `tsc --noEmit` type-check only |
|
||||||
|
|
||||||
|
To load an unpacked build: in Firefox/Zen, go to `about:debugging#/runtime/this-firefox`
|
||||||
|
→ "Load Temporary Add-on" → select any file inside `.output/firefox-mv3/`.
|
||||||
|
|
||||||
|
### Building from source for a store submission
|
||||||
|
|
||||||
|
No build secrets, environment variables, or private dependencies are required —
|
||||||
|
everything needed to build is in this repository and on the public npm registry, pinned
|
||||||
|
via `package-lock.json`.
|
||||||
|
|
||||||
**Environment**
|
|
||||||
- Node.js 22.x (built and tested on 22.11.0)
|
- Node.js 22.x (built and tested on 22.11.0)
|
||||||
- npm 11.x (built and tested on 11.14.1)
|
- npm 11.x (built and tested on 11.14.1)
|
||||||
|
|
||||||
**Steps**
|
|
||||||
```sh
|
```sh
|
||||||
npm install # also runs `wxt prepare` via postinstall
|
npm install
|
||||||
npm run build:firefox
|
npm run build:firefox # → .output/firefox-mv3/
|
||||||
|
npm run zip:firefox # → .output/*.zip
|
||||||
```
|
```
|
||||||
|
|
||||||
Output is written to `.output/firefox-mv3/`. To produce the uploaded `.zip` directly:
|
## Project structure
|
||||||
|
|
||||||
```sh
|
```
|
||||||
npm run zip:firefox
|
/src
|
||||||
|
/background WebSocket connection to the backend, lock state, messaging
|
||||||
|
/content-scripts
|
||||||
|
/adapters Site-specific selectors + DOM strategy (axiom.trade first)
|
||||||
|
/interventions Visual lock treatments (blur-disable, full-block stub)
|
||||||
|
/popup Status, lock reason, Settings panel
|
||||||
|
/notifications Toast/banner injected into the page
|
||||||
|
/shared Typed message contracts, config
|
||||||
```
|
```
|
||||||
|
|
||||||
Output zip is written to `.output/`.
|
Decision-making (backend), site detection, and enforcement are deliberately decoupled —
|
||||||
|
adding a new supported site or a new intervention type never requires touching the
|
||||||
|
other two. Full detail in [`CLAUDE.md`](CLAUDE.md).
|
||||||
|
|
||||||
No build secrets, environment variables, or private dependencies are required — everything
|
## Status
|
||||||
needed to build is in this repository and on the public npm registry, pinned via
|
|
||||||
`package-lock.json`.
|
|
||||||
|
|
||||||
## Development
|
Early public beta. Working end-to-end: real Phantom wallet sign-in, the `/ws`
|
||||||
|
connection with reconnect handling, real-time lockout on axiom.trade, and
|
||||||
|
per-user-configurable thresholds. See [`CLAUDE.md`](CLAUDE.md#current-status) for the
|
||||||
|
full current-state summary.
|
||||||
|
|
||||||
- `npm run dev:firefox` — dev build + watch targeting Firefox/Zen, auto-opens a temporary
|
## Contributing
|
||||||
profile with the extension loaded.
|
|
||||||
- `npm run compile` — `tsc --noEmit` type-check only.
|
Issues and pull requests are welcome — this is a young project and honest feedback
|
||||||
|
(bug reports especially) is genuinely useful right now. Please open an issue at
|
||||||
|
[github.com/osias-trade/copilot/issues](https://github.com/osias-trade/copilot/issues).
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
Apache License 2.0 — see [`LICENSE`](LICENSE).
|
[Apache License 2.0](LICENSE).
|
||||||
|
|||||||
Reference in New Issue
Block a user