LOOM / 01

Projects & Applications

A project starts as a place to work. It becomes part of LOOM when you declare which parts need the system.

Start with ordinary files

A research project might contain notes, several repositories and a small service. A writing project might contain no code at all. Neither needs to become an application just to have a name, a home and an understandable state.

LOOM creates a minimal project structure. The folders are ordinary folders: you can edit them with your preferred tools, arrange the work as it develops, and choose where Git belongs. Creating a project does not initialize a Git repository or silently turn every directory into a managed resource.

research-sync/
|-- AGENTS.md
|-- .loom/
|   `-- project.yaml
|-- .project/
|   |-- OVERVIEW.md
|   |-- STATE.md
|   |-- ROADMAP.md
|   |-- MAP.md
|   `-- protocols/WORKFLOW.md
|-- notes/
`-- repos/

Illustrative project structure. The files describe identity, context and work; their presence alone does not deploy a service or enroll all content for search.

This leaves room for the project to find its own shape. A new folder is not an administrative event. Declare a repository, a knowledge source or an application when you actually need LOOM to do something with it.

Context explains. Declarations connect.

.project/ is the editable account of what the project is doing: its purpose, current state, priorities and working conventions. AGENTS.md points an arriving agent toward that context. It is useful to people too, and remains readable without a running LOOM installation.

.loom/project.yaml serves a different purpose. It identifies the project and declares the resources LOOM should manage. The system does not infer deployment intent from a README, discover repository ownership by guessing at child folders, or treat a progress note as an instruction to change the host.

Registered project context can be projected into Provenance discovery. That projection is an observation of the source files, not an automatic endorsement of every statement inside them. Accepted decisions have a separate evidence and reconciliation lifecycle. Older repository-specific .repo/ context remains a compatibility path, not the default shape of a new project.

One declaration, an inspectable operation

Consider an illustrative research-sync application: a WebDAV service that keeps a research library available across devices. Its source implements the application. Its declaration connects a supported application package to a host, persistent data, a credential reference and, optionally, a public endpoint.

Context
Understand the project, its declarations and the work already recorded.
Plan
Resolve the application and its prerequisites. Explain what can happen and what is missing.
Apply
Execute the reviewed plan with a request identity, retaining progress if only part succeeds.
Status
Inspect installation, startup readiness and publication, rather than equating a started process with a finished deployment.

The project workflow separates understanding, a proposed change, execution and observed state. A plan is not evidence that the application is already running.

The application path brings those related operations together. It can report a missing host grant or credential binding before the developer has to discover the same prerequisite through several unrelated failures. If installation succeeds but a later step fails, the result describes a partial operation; supported resume behavior continues from recorded progress rather than pretending the first attempt never happened.

The short vocabulary is loom project context, plan, apply and status. The plan identity and idempotency key used by apply bind a reviewed change and its retry. Exact syntax and resource schemas belong in the linked reference documentation, not in the project's everyday narrative.

The project outlives a deployment

The WebDAV development pilot reached a working deployment and device use. That is useful evidence for this workflow, not proof that every application shape or recovery scenario is finished.

A project can also stop being active. Physical archiving preserves its files and lifecycle history; restoring it returns an inactive workspace, not permission to restart every service. Storage & Recovery explains that distinction.

The current developer preview is CLI-led. Some Portal creation forms still reflect earlier project models, and installation remains operator-led. The direction is fewer decisions at setup, clearer declarations when a system connection is needed, and useful context when a human or agent arrives to work.