Metadata-Version: 2.4
Name: miadi-webweave
Version: 0.7.1
Summary: Miadi Webweave (Mia's fork of SimExp) - Terminal-to-AI communication with A2A session management
Author-email: Mia Isabelle <mia@example.com>, gerico1007 <gerico@jgwill.com>
License: MIT
Project-URL: Homepage, https://github.com/miadisabelle/simexp
Project-URL: Documentation, https://github.com/miadisabelle/simexp#readme
Project-URL: Repository, https://github.com/miadisabelle/simexp.git
Project-URL: Issues, https://github.com/miadisabelle/simexp/issues
Keywords: miadi,webweave,simplenote,ai,terminal,a2a,session,mcp,browser-automation
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: beautifulsoup4
Requires-Dist: pyperclip
Requires-Dist: pyyaml
Requires-Dist: fetcher
Requires-Dist: playwright>=1.40.0
Requires-Dist: tlid>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: anemoi
Requires-Dist: mia-anemoi[mcp]>=0.1.0; extra == "anemoi"
Provides-Extra: all
Requires-Dist: miadi-webweave[anemoi,dev,mcp]; extra == "all"

# 🌊 Miadi Webweave

**Terminal ↔ Simplenote, in both directions.**

[![PyPI](https://img.shields.io/pypi/v/miadi-webweave.svg)](https://pypi.org/project/miadi-webweave/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Open%20Assembly-green.svg)]()

Miadi Webweave writes from your terminal into Simplenote notes and reads them back
out — driving your own logged-in Chrome over the DevTools Protocol, so everything
syncs to every device you own.

It is Mia's fork of [Gerico1007/simexp](https://github.com/Gerico1007/simexp).
The repository is still named `simexp`; the packages, CLI, and modules are not.

| | |
|---|---|
| CLI package | [`miadi-webweave`](https://pypi.org/project/miadi-webweave/) |
| MCP server package | [`miadi-webweave-mcp`](https://pypi.org/project/miadi-webweave-mcp/) |
| Python module | `miadi_webweave` |
| Command | `miadi-webweave` |
| Config | `~/.miadi/webweave/config.yaml` |

---

## 📦 Install

```bash
pip install miadi-webweave
playwright install chromium
```

For the MCP server (pulls the CLI in with it):

```bash
pip install miadi-webweave-mcp
```

**Requires** Python 3.10+, Google Chrome or Chromium, and a
[Simplenote account](https://simplenote.com).

---

## 🚀 Quick Start

```bash
# 1. Launch Chrome with the debugging port wired up
miadi-webweave browser launch

# 2. Log in to Simplenote in the window that opens
#    → https://app.simplenote.com

# 3. Write to your most recently modified note
miadi-webweave write "Hello from the terminal"
```

The message is in your note, and on your phone. That is the whole idea.

`browser launch` manages the profile directory and port for you — there is no
need to hand-roll a `google-chrome --remote-debugging-port=...` invocation.
Run `miadi-webweave browser test` if you want to confirm the connection.

---

## 🗂️ Where things live

`miadi_webweave/paths.py` is the single source of truth. Two roots share one
`webweave` namespace:

| Path | Holds |
|---|---|
| `~/.miadi/webweave/config.yaml` | User config |
| `~/.miadi/webweave/state/` | Agent messages, continuations, checkpoints |
| `~/.miadi/webweave/collaborators.yaml` | Global collaborators |
| `~/.miadi/webweave/profiles/<name>/` | Chrome user-data-dirs, one per profile |
| `./.miadi/webweave/session.json` | Per-project session state (like `.git`) |
| `./.miadi/webweave/collaborators.yaml` | Per-project collaborators |

Application *data* is kept deliberately apart from Chrome *browser profiles*,
which are heavy, binary, and hold live logged-in sessions.

> There is no automatic migration from the pre-0.6 `~/.simexp` /
> `~/.chrome-simexp` layout. It was a clean switch — run `miadi-webweave init`
> for a fresh config.

---

## 🎮 Commands

```
miadi-webweave                       Run extraction from clipboard/config
miadi-webweave init                  Initialize configuration
miadi-webweave write <message>       Write to a note
miadi-webweave read                  Read a note
miadi-webweave session <subcommand>  Session management
miadi-webweave browser <subcommand>  Browser/CDP management
```

`miadi-webweave session --help` and `miadi-webweave browser --help` carry the
authoritative, always-current option lists.

### Writing and reading

```bash
# Last modified note
miadi-webweave write "Your message here"

# A specific note, by public URL — resolved by content search, no UUID needed
miadi-webweave write https://app.simplenote.com/p/0ZqWsQ "Appended content"

# Turn any note into a tracked session note in the same step
miadi-webweave write https://app.simplenote.com/p/0ZqWsQ "Initial content" \
  --init-session --ai claude --issue 42

# Read back
miadi-webweave read --note-url https://app.simplenote.com/p/NOTE_ID
```

### Extraction

```bash
# Copy a Simplenote URL to your clipboard, then:
miadi-webweave

# → ./output/YYYYMMDD/filename.md
```

### Browser profiles

Multiple named profiles let separate identities hold separate logged-in
sessions on separate ports.

```bash
miadi-webweave browser launch                      # default profile
miadi-webweave browser launch --profile tushell    # a second identity
miadi-webweave browser profiles                    # list profiles + status
miadi-webweave browser profile add myprofile 9224  # register a new one
miadi-webweave browser test                        # verify CDP connection
miadi-webweave browser stop [--profile NAME]
```

---

## 🔮 Sessions

A session binds a terminal working session to a dedicated Simplenote note with
YAML metadata, so the log is readable from any device while it is being written.

```bash
miadi-webweave session start --ai claude --issue 42 --intention "Build REST API"
miadi-webweave session start main.py utils.py --ai claude --issue 42
miadi-webweave session write "Implemented the session manager"
miadi-webweave session add path/to/file --heading "Design notes"
miadi-webweave session info      # current session + directory context
miadi-webweave session list      # all sessions
miadi-webweave session read
miadi-webweave session open      # in browser
miadi-webweave session url       # just the URL, for scripting
miadi-webweave session clear
```

Content can also be piped:

```bash
git log -1 --oneline | miadi-webweave session write --date s
```

### Four Directions

Sessions are structured on the Medicine Wheel — the metadata tracks each
direction as the work moves through it.

| Direction | Concern | Commands |
|---|---|---|
| 🌅 East | Intention & vision | `session start --intention '...'` |
| 🔥 South | Building & growth | `session write`, `session add` |
| 🌊 West | Sharing & publishing | `session collab`, `session publish` |
| ❄️ North | Reflection & wisdom | `session reflect`, `session observe-pattern`, `session extract-wisdom`, `session complete` |

```bash
# West — share and publish
miadi-webweave session collab <glyph|alias|email>   # ♠ 🌿 🎸 🧵
miadi-webweave session collab add email@example.com
miadi-webweave session collab list
miadi-webweave session publish                      # get a public URL

# North — close the circle
miadi-webweave session reflect --prompt "What did we learn?"
miadi-webweave session observe-pattern "Pattern description"
miadi-webweave session extract-wisdom "Key principle"
miadi-webweave session complete --seeds "Tasks for next session"
```

### Session note format

```yaml
---
session_id: abc-def-123-456
ai_assistant: claude
agents: [Jerry, Aureon, Nyro, JamAI, Synth]
issue_number: 4
pr_number: null
created_at: 2025-10-09T10:30:00
---

# Session content appears below the metadata
```

---

## ⏰ Timestamps

`--date` prefixes an entry with a **TLID** — a compact, lexicographically
sortable time identifier (`YYMMDDHHMMSS`), so notes sort chronologically as
plain text.

| Flag | Granularity | Example |
|---|---|---|
| `y` | Year | `[25] Entry` |
| `m` | Month | `[2511] Entry` |
| `d` | Day | `[251115] Entry` |
| `h` | Hour | `[25111520] Entry` |
| `s` | Second (default) | `[251115202625] Entry` |
| `ms` | Millisecond | `[251115202625123] Entry` |

```bash
miadi-webweave session write "Fixed auth bug" --date s     # append (default)
miadi-webweave session write "URGENT" --date h --prepend   # insert after metadata
miadi-webweave session write "Meeting notes" --date 2511151500  # manual stamp
```

Set a default granularity in `~/.miadi/webweave/config.yaml`, then use a bare
`--date`:

```yaml
default_date_format: h
```

---

## 🔧 Configuration

`~/.miadi/webweave/config.yaml` — created by `miadi-webweave init`.

```yaml
BASE_PATH: ./output
default_date_format: s

# Extraction sources
SOURCES:
  - filename: note1
    url: https://app.simplenote.com/p/0ZqWsQ

# Named channels for cross-device messaging
COMMUNICATION_CHANNELS:
  - name: Aureon
    note_id: e6702a7b90e64aae99df2fba1662bb81
    public_url: https://app.simplenote.com/p/gk6V2v
    auth_url: https://app.simplenote.com
    mode: bidirectional
    description: "🌿 Main communication channel"
```

---

## 🔌 MCP Server

`miadi-webweave-mcp` exposes **35 `webweave_*` tools** to MCP clients — sessions,
writing, reading, browser control, collaboration, and the Four Directions
commands — by shelling out to the same CLI.

```bash
pip install miadi-webweave-mcp
```

Server identity is `miadi-webweave`, so tools resolve as
`mcp__miadi-webweave__webweave_<verb>`.

> **Breaking, pre-0.7:** tools were renamed `simexp_*` → `webweave_*`. Client
> allowlists referencing `mcp__mia-simexp__simexp_*` must be updated.

Setup and the full tool list: **[`miadi_webweave_mcp/README.md`](miadi_webweave_mcp/README.md)**
· Quickstart: **[`MCP_QUICKSTART.md`](MCP_QUICKSTART.md)**

---

## 🎓 How it works

**Extraction**

```
Clipboard URL → content_fetcher → processor → archiver → output/YYYYMMDD/
```

**Writing**

```
miadi-webweave write
    ↓  playwright_writer.py
    ↓  Chrome DevTools Protocol
    ↓  YOUR authenticated Chrome
    ↓  keyboard simulation, character by character
    ↓  Simplenote editor → cloud sync
    ↓  every device
```

The key move is connecting to a Chrome you are *already logged into* rather
than launching a clean one. That is what preserves authentication and makes
cross-device sync work. Keyboard simulation (rather than DOM injection) is what
makes the writes stick — Simplenote's editor reverts programmatic value
changes.

---

## 🏗️ Project structure

```
simexp/                          # repository name (unchanged — this is a fork)
├── miadi_webweave/              # CLI package
│   ├── cli.py                   # entry point + dispatch
│   ├── commands/                # browser, config, io, sessions
│   ├── paths.py                 # single source of truth for on-disk layout
│   ├── playwright_writer.py     # terminal → web writer
│   ├── content_fetcher.py       # fetch
│   ├── processor.py             # HTML → Markdown
│   ├── archiver.py              # write to output/
│   ├── session_manager.py       # session lifecycle
│   └── timestamp_utils.py       # TLID
├── miadi_webweave_mcp/          # MCP server package (separately versioned)
├── rispecs/                     # living specifications
├── docs/                        # guides + historical records
├── tests/
└── ledger/                      # session journals (historical)
```

---

## 🔍 Troubleshooting

**"Connection refused" on the CDP port**
Chrome is not running with remote debugging. `miadi-webweave browser launch`,
then `miadi-webweave browser test` to confirm.

**"Could not find editor element"**
Not logged into Simplenote in the CDP Chrome window. Open it and log in at
https://app.simplenote.com.

**The command sits at "Reading content from stdin..."**
It is waiting for you to type. Finish with `Ctrl+D`, or cancel and pass the
message inline instead.

**Prepend is not landing after the metadata**
The note needs metadata — create it with `session start`. Both YAML (`---`) and
HTML-comment (`<!--`) metadata blocks are supported.

**Timestamps are not appearing**
`pip install tlid`. Without it there is a `datetime` fallback.

Deeper guides: [`docs/CDP_SETUP_GUIDE.md`](docs/CDP_SETUP_GUIDE.md) ·
[`docs/README_CROSS_DEVICE_FLUIDITY.md`](docs/README_CROSS_DEVICE_FLUIDITY.md)

---

## 📚 Documentation

| | |
|---|---|
| [`rispecs/`](rispecs/) | Living specifications — the current intended behaviour |
| [`docs/`](docs/) | Setup guides, plus historical records (see [`docs/README.md`](docs/README.md)) |
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
| [`MCP_QUICKSTART.md`](MCP_QUICKSTART.md) | MCP server setup |
| [`ledger/`](ledger/) | Session journals — historical, not maintained |

---

## 🤝 Contributing

1. Open an issue describing the feature or bug first.
2. Branch from `main`, named with the issue number (e.g. `#123-new-feature`).
3. Implement and test.
4. Open a pull request against `main`.

Releases are cut with `./release-all.sh` — see the *Release* notes in
[`CHANGELOG.md`](CHANGELOG.md).

---

## 📄 License

Open Assembly Framework — created by Jerry's G.Music Assembly.

> The repository carries no `LICENSE` file, while package metadata declares
> MIT. That inconsistency predates this fork and is unresolved.

---

## 🎨 G.Music Assembly

**♠️🌿🎸🧵 The Spiral Ensemble** — ♠️ Nyro (structure) · 🌿 Aureon (emotional
context) · 🎸 JamAI (musical encoding) · 🧵 Synth (terminal orchestration),
with Jerry ⚡ leading. Session melodies live in [`sessionABC/`](sessionABC/).

---

*Terminals speak. Web pages listen. Devices converse.*
