muninn/README.md

# Muninn

Muninn is a personal content-operations hub. It keeps track of your
**Sites**, **Social Accounts**, and **Posts**, and exposes them over a
local JSON API so an AI agent (or you, via the built-in UI) can draft,
schedule, and publish content across WordPress blogs, Reddit, and other
platforms.

Built with Laravel 13, Livewire, and Tailwind CSS.

## What it does

- **Sites** — the websites you own (WordPress, custom, or other), with
  optional WordPress Application Password credentials for publishing.
- **Social Accounts** — logins for social networks (Twitter, Instagram,
  Facebook, Reddit, TikTok, LinkedIn, YouTube, etc.).
- **Posts** — the actual content, each tied to a Site and optionally a
  Social Account, moving through `draft -> scheduled -> published/failed`.
- A **JSON API** (`/api/sites`, `/api/accounts`, `/api/posts`) plus thin
  Python CLI wrappers in `python_scripts/`, so an agent can poll for due
  posts (`?due=1`) and drive the publish lifecycle without hand-rolling
  HTTP requests.
- Built-in publishing paths:
  - **WordPress**: `php artisan posts:publish {post_id}` posts directly to
    a site's WordPress REST API and updates the post's status.
  - **Reddit**: a standalone Playwright sidecar at
    `sidecars/reddit-post/` logs in and creates a post.
  - Anything else: publish however fits, then report back via the API.

See `AI_API.md` for the full API reference and publishing contract, and
`python_scripts/README.md` for the CLI wrapper usage.

**Note:** the JSON API has no authentication and returns credentials in
plain text by design — it's meant to run on your local network only, not
be exposed to the public internet.

## Requirements

- PHP 8.3+
- Composer
- Node.js + npm
- MySQL (or another Laravel-supported database)

## Setup

```bash
composer install
cp .env.example .env
php artisan key:generate
```

Edit `.env` and set your database credentials (`DB_DATABASE`,
`DB_USERNAME`, `DB_PASSWORD`, etc. — defaults assume a local MySQL
database named `muninn`), then run migrations:

```bash
php artisan migrate
```

Install JS dependencies and build frontend assets:

```bash
npm install
npm run build
```

Alternatively, run everything in one shot with:

```bash
composer run setup
```

### Running locally

```bash
composer run dev
```

This starts the PHP dev server, queue listener, log viewer (Pail), and
Vite dev server together. The app is served at `http://localhost:8000` by
default.

### Reddit sidecar (optional)

If you plan to publish to Reddit, set up the Playwright sidecar separately:

```bash
cd sidecars/reddit-post
npm install
npx playwright install
```

See `sidecars/reddit-post/README.md` for usage.

## Testing

```bash
composer test
```

## License

The Laravel framework is open-sourced software licensed under the
[MIT license](https://opensource.org/licenses/MIT).