Add Core Concepts and fix Introduction

fern/concepts/diagrams.mdx

@@ -0,0 +1,23 @@
+# Diagrams
+
+Diagrams are C4 visualisations of your model. They are views onto the underlying model [objects](/core-concepts/model-objects) and [connections](/core-concepts/model-connections). The model data exists independently of any diagram, and the same object can appear in multiple diagrams.
+
+---
+
+## Diagram types
+
+Each diagram type maps to a C4 level of abstraction:
+
+| Type | C4 Level | Description |
+| --- | --- | --- |
+| `context-diagram` | Level 1 | Shows a `system` in the context of its actors and external systems |
+| `app-diagram` | Level 2 | Shows the `app` and `store` containers inside a `system` |
+| `component-diagram` | Level 3 | Shows the `component` objects inside an `app` or `store` |
+
+---
+
+## Related concepts
+
+- [Model Objects](/core-concepts/model-objects)
+- [Flows](/core-concepts/flows)
+- [Versions](/core-concepts/versions)

fern/concepts/domains.mdx

@@ -0,0 +1,34 @@
+# Domains
+
+Domains are named groupings that organise [model objects](/core-concepts/model-objects) into bounded contexts. They map closely to the <Tooltip tip="A software design approach that focuses on modeling software to match a domain. It divides a large system into bounded contexts, each of which have their own model.">Domain-Driven Design (DDD)</Tooltip>.
+
+---
+
+## What a domain is
+
+Every model object in a version belongs to exactly one domain. Domains provide a way to segment a large architecture either by business unit (e.g., `Payments`) or by team ownership (e.g., `platform`).
+
+---
+
+## Creating domains
+
+Create a domain in a version:
+
+<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/domains" />
+
+---
+
+## Filtering model objects by domain
+
+Use the `GET` endpoint with query parameter `?filter[domainId]={domainId}` to filter objects.
+
+<EndpointRequestSnippet endpoint="GET /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
+
+This is useful for extracting a bounded-context slice of the architecture for reports or external tools.
+
+---
+
+## Related concepts
+
+- [Model Objects](/core-concepts/model-objects)
+- [Model Connections](/core-concepts/model-connections)

fern/concepts/flows.mdx

@@ -0,0 +1,19 @@
+# Flows
+
+Flows are step-by-step sequences that trace a path through your architecture model. Useful for documenting user journeys, request paths, data flows, or any scenario where ordering and directionality matter.
+
+---
+
+## What a flow is
+
+A flow lives inside a [diagram](/core-concepts/diagrams) and consists of an ordered list of **steps**. Each step identifies a model [object](/core-concepts/model-objects) or [connection](/core-concepts/model-connections) that participates at that point in the sequence. When viewing a flow in the IcePanel UI, the relevant objects and connections are highlighted in order.
+
+Flows are distinct from model connections: a connection represents a static relationship between two objects, while a flow represents a dynamic sequence that may traverse many objects and connections.
+
+---
+
+## Related concepts
+
+- [Model Objects](/core-concepts/model-objects)
+- [Model Connections](/core-concepts/model-connections)
+- [Diagrams](/core-concepts/diagrams)

fern/concepts/landscapes.mdx

@@ -0,0 +1,75 @@
+# Landscapes
+
+A landscape is the primary workspace in IcePanel. It holds a complete C4 architecture model including all objects, connections, diagrams, flows, and versions.
+
+---
+
+## What a landscape contains
+
+Each landscape is versioned. All models like objects, connections, diagrams, flows, and domains live inside a [version](/core-concepts/versions) of a landscape.
+
+When you create a landscape, IcePanel automatically creates an initial `latest` version that you can modify immediately.
+
+Create a landscape:
+
+<EndpointRequestSnippet endpoint="POST /organizations/{organizationId}/landscapes" />
+
+The response returns both the `landscape` and the initial `version` objects.
+
+List all landscapes in your organization:
+
+<EndpointRequestSnippet endpoint="GET /organizations/{organizationId}/landscapes" />
+
+---
+
+## URL patterns
+
+Landscape endpoints are available in two forms.
+
+**Organization-scoped** (includes org context, useful when you have the org ID in scope):
+```
+GET /organizations/{organizationId}/landscapes/{landscapeId}
+```
+
+**Landscape-scoped** (shorter, useful when you already know the landscape ID):
+```
+GET /landscapes/{landscapeId}
+```
+
+All version-scoped resources (model objects, diagrams, flows, etc.) use only the landscape-scoped pattern:
+```
+GET /landscapes/{landscapeId}/versions/{versionId}/model/objects
+```
+
+You can also specify `latest` as a shorthand for getting the latest version:
+
+```
+GET /landscapes/{landscapeId}/versions/latest/model/objects
+```
+
+---
+
+## Duplicate vs copy
+
+IcePanel provides two operations for replicating a landscape:
+
+| Operation | Description |
+| --- | --- |
+| **Duplicate** | Creates a full copy of the landscape within the same organization, including all versions and model content |
+| **Copy** | Copies the model content of a specific version into a different target landscape. This is useful for merging two models or seeding a new landscape from an existing one |
+
+Duplicate a landscape:
+
+<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/duplicate" />
+
+Copy to another landscape:
+
+<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/copy" />
+
+---
+
+## Related concepts
+
+- [Versions](/core-concepts/versions)
+- [Model Objects](/core-concepts/model-objects)
+- [Diagrams](/core-concepts/diagrams)

fern/concepts/model-connections.mdx

@@ -0,0 +1,47 @@
+# Model Connections
+
+Model connections are the edges of the <Tooltip tip="Actors, systems, services, and components that make up your software architecture.">model objects</Tooltip> in your architecture. They represent relationships, dependencies, API calls, data flows, or any meaningful interaction between two model objects.
+
+---
+
+## Creating connections
+
+<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/model/connections" />
+
+---
+
+## Filtering connections
+
+The `GET /model/connections` endpoint supports filtering:
+
+| Query parameter | Description |
+| --- | --- |
+| `filter[originId]` | Connections starting from a specific object |
+| `filter[targetId]` | Connections ending at a specific object |
+| `filter[viaId]` | Connections passing through a specific object |
+| `filter[direction]` | `outgoing` or `bidirectional` |
+| `filter[status]` | Status lifecycle value |
+| `filter[tagIds][]` | One or more tag IDs |
+| `filter[technologyIds][]` | One or more technology IDs |
+| `filter[labels][key]` | Label key-value pair |
+| `filter[name]` | Partial name match |
+| `filter[linked]` | `true` to return only connections with at least one link |
+
+---
+
+## Status lifecycle
+
+Connections share the same four-state lifecycle as [model objects](/core-concepts/model-objects):
+
+| Status | Description |
+| --- | --- |
+| `live` | Active dependency or relationship |
+| `future` | Planned but not yet implemented |
+| `deprecated` | In use but being phased out |
+| `removed` | Retired, kept for historical reference |
+
+---
+
+## Related concepts
+
+- [Model Objects](/core-concepts/model-objects)

fern/concepts/model-objects.mdx

@@ -0,0 +1,93 @@
+# Model Objects
+
+Model objects are the nodes in your architecture graph. They represent the actors, systems, services, and components that make up your software architecture.
+
+---
+
+## Object types
+
+IcePanel uses the <Tooltip tip="Framework for visualising software architecture through four levels of abstraction: Context, Containers, Components, and Code">C4 model</Tooltip>'s levels of abstraction. Each object type maps to a C4 level:
+
+| Type | C4 Level | Description |
+| --- | --- | --- |
+| `root` | — | The root node of every [domain](/core-concepts/domains). There is exactly one per domain. All top-level systems and actors are children of the root. |
+| `actor` | Level 1 | A person or external role that interacts with your architecture (e.g. "Customer", "Admin") |
+| `system` | Level 1 | A top-level software system (e.g. "IcePanel") |
+| `group` | Level 1 | A visual grouping (e.g. "Worker Pool", "Subnet") |
+| `app` | Level 2 | A deployable unit (container) inside a system: a service, web app, mobile app, or queue |
+| `store` | Level 2 | A persistent data store inside a system: a database, blob store, or cache |
+| `component` | Level 3 | An internal building block inside an `app` or `store` |
+
+---
+
+## The parent–child hierarchy
+
+Model objects form a tree. Every object except `root` has a `parentId` pointing to its parent:
+
+```
+root
+├── actor: Customer
+├── system: Payment Service
+│   ├── app: API Gateway
+│   │   ├── component: Auth Middleware
+│   │   └── component: Rate Limiter
+│   ├── app: Payment Processor
+│   └── store: Transactions DB
+└── system: Auth Platform (external)
+```
+
+---
+
+## Creating objects
+
+To create a new object, specify the `landscapeId` and either the `versionId` or `latest`:
+<EndpointRequestSnippet endpoint="POST /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
+
+---
+
+## Filtering objects
+
+To find the root object (required as `parentId` when creating top-level objects), use the query parameter `?filter[type]=root`
+
+<EndpointRequestSnippet endpoint="GET /landscapes/{landscapeId}/versions/{versionId}/model/objects" />
+
+The `GET /model/objects` endpoint supports the following filters:
+
+| Query parameter | Description |
+| --- | --- |
+| `filter[type]` | Object type |
+| `filter[status]` | Status lifecycle value |
+| `filter[parentId]` | Direct parent ID |
+| `filter[domainId]` | Domain ID |
+| `filter[external]` | `true` / `false` |
+| `filter[tagIds][]` | One or more tag IDs |
+| `filter[teamIds][]` | One or more team IDs |
+| `filter[technologyIds][]` | One or more technology IDs |
+| `filter[labels][key]` | Label key-value pair |
+| `filter[name]` | Partial name match |
+| `filter[linked]` | `true` to return only objects with at least one link |
+
+---
+
+## Status lifecycle
+
+Objects and connections share a four-state lifecycle representing their architectural status:
+
+```
+live  →  deprecated  →  removed →  future
+```
+
+| Status | Description |
+| --- | --- |
+| `live` | Current, active element |
+| `future` | Planned but not yet built |
+| `deprecated` | Still in use but being phased out |
+| `removed` | Retired, kept for historical reference |
+
+Use the `filter[status]` query parameter to retrieve only objects with a given status.
+
+---
+
+## Related concepts
+
+- [Model Connections](/core-concepts/model-connections)

fern/concepts/organizations.mdx

@@ -0,0 +1,16 @@
+# Organizations
+
+An organization is the top-level model in IcePanel. It owns all landscapes, manages billing, and controls who has access.
+
+---
+
+Every API key and every landscape belongs to exactly one organization. The `organizationId` is the first path parameter you'll need for most operations.
+
+<EndpointRequestSnippet endpoint="GET /organizations/{organizationId}" />
+
+---
+
+## Related concepts
+
+- [Landscapes](/core-concepts/landscapes)
+- [Versions](/core-concepts/versions)