diff --git a/content/docs/(overview)/introduction.mdx b/content/docs/(overview)/introduction.mdx index 65db5f09..ef48542d 100644 --- a/content/docs/(overview)/introduction.mdx +++ b/content/docs/(overview)/introduction.mdx @@ -9,6 +9,14 @@ Most apps keep their own copy of your data, in their own shape. Marfa keeps it i Marfa is open source under the Apache License 2.0. The rules it follows are written down in [the contract](https://github.com/withmarfa/marfa/tree/main/conformance/spec) and checked by tests. +## How it fits together + +One running Marfa is an **instance**. It belongs to one person, its **owner**, and runs on a computer they choose: their own Mac, a home server, or a host such as Railway. Everything else connects to it. + + + +Apps, scripts and AI agents read and write over Marfa's HTTP API, each with a credential that reaches only the data it was given. Connectors bring in records from other services. [How Marfa works](/how-marfa-works) explains each part. + ## What you can do with Marfa - **Keep your data when you change apps.** Stop using an app, and everything it saved stays in Marfa for the next one. @@ -19,14 +27,6 @@ Marfa is open source under the Apache License 2.0. The rules it follows are writ If you know Apple's platforms, Marfa is **like iCloud, but for structured data and open to any app**. It's also **like HealthKit, but for any kind of data**: each app asks for the types it needs and sees no items of any other type. -## How it fits together - -One running Marfa is an **instance**. It belongs to one person, its **owner**, and runs on a computer they choose: their own Mac, a home server, or a host such as Railway. Everything else connects to it. - - - -Apps, scripts and AI agents read and write over Marfa's HTTP API, each with a credential that reaches only the data it was given. Connectors bring in records from other services. [How Marfa works](/how-marfa-works) explains each part. - ## What Marfa isn't - **Not for teams.** An instance belongs to one person. It holds that person's data, and other people don't collaborate in it. diff --git a/content/docs/(overview)/overview.mdx b/content/docs/(overview)/overview.mdx index 089ab202..32997760 100644 --- a/content/docs/(overview)/overview.mdx +++ b/content/docs/(overview)/overview.mdx @@ -1,46 +1,38 @@ --- title: Overview -description: Marfa is a shared data layer for your apps, and you run it yourself. Find the page you need, from your first instance to the API reference. +description: Marfa is a shared data layer for your apps, and you run it yourself. --- -Marfa keeps your data in one place you own, as typed items, so your apps, scripts and AI agents work from the same data through one API. +Your notes, tasks, bookmarks and files live in one instance, as typed items. Your apps, scripts and AI agents read and write them through one API, each reaching only what you allow, and apps built on the Swift SDK keep working offline. These docs cover running an instance and building on it. Marfa is early, so expect breaking changes until version 1.0. -## Get started +## Start here What Marfa is, what you can do with it, and where it runs. Start an instance on your computer and write your first note. - The parts of Marfa, and how they fit together. - The words Marfa uses, each with one meaning. +[How Marfa works](/how-marfa-works) then explains the parts, and the [Glossary](/glossary) defines the words these docs use. + ## Build on Marfa - - An iPhone and Mac app that works offline. - Give an agent a key that reaches only what it needs. - Bring records from another service into Marfa. - Register a type of your own, with its fields. - +Apps and agents share the same data, through the Swift and TypeScript SDKs, the CLI or plain HTTP. + +- [Build an app with Swift](/guides/swift-app): an iPhone and Mac app that works offline. +- [Use Marfa with AI agents](/guides/ai-agents): give an agent a key that reaches only what it needs. +- [Build a connector](/guides/connector): bring records from another service into Marfa. +- [Define a type](/guides/define-a-type): register a type of your own, with its fields. ## Run Marfa - - Run an instance on your Mac, a home server or Railway. - Copy an instance's data and secrets, and bring them back. - Check that a new build can open your data, then move to it. - The cause and the fix for the problems people meet first. - +An instance is one SQLite database file and a folder of files, on your Mac, a home server or Railway. + +- [Deploy](/guides/deploy): choose where it runs and how your devices reach it. +- [Back up and restore](/guides/back-up-and-restore): keep a copy of the data and secrets, and bring them back. +- [Troubleshooting](/guides/troubleshooting): the cause and the fix for the problems people meet first. ## Reference - - The types, edges, events and permissions every instance ships. - Every operation, with its requests and answers. - Marfa's command-line tool, for you and your agents. - Call your instance from TypeScript or JavaScript. - Give an iOS or macOS app a working copy that reads offline. - What each release changed. - +The [Catalog](/catalog) lists the types, edges, events and permissions every instance ships. The [HTTP API](/api-reference), the [CLI](/cli) and the [Swift](/swift-sdk) and [TypeScript](/typescript-sdk) SDKs are each documented in full, and the [Changelog](/changelog) says what each release changed.