[docs] Add updated modular documentation
This includes updated documentation for:
* Agents
* Modules
* Shells
* Stories
* Entities
* Intents
It also provides an overview page.
Not all of the documentation is equally well fleshed out, and future
changes are in the works.
TESTED=N/A
MF-86 #done
Change-Id: Id777b6b39b6ed88535de7390fe27aba57ec5564b
diff --git a/docs/modular/agent.md b/docs/modular/agent.md
index 7c1daf7..27c9401 100644
--- a/docs/modular/agent.md
+++ b/docs/modular/agent.md
@@ -1,14 +1,85 @@
-fuchsia::modular::Agent
-=====
+## Agents
-An agent is an application that implements the fuchsia::modular::Agent interface, whose lifecycle
-is not tied to any Story and is a singleton in User scope. An agent can be
-invoked by other components or by the system in response to triggers. An agent
-can terminate itself or be terminated by the system. An agent can provide /
-receive services to / from other applications, send / receive messages and give
-suggestions to the user.
+An `Agent` is a singleton-per-session component which runs outside of
+the scope of a Story without any graphical UI.
-## See also:
-[fuchsia::modular::Agent](../services/agent/agent.fidl)
-[fuchsia::modular::AgentContext](../services/agent/agent_context.fidl)
-[fuchsia::modular::AgentController](../services/agent/agent_controller/agent_controller.fidl)
+Agents can schedule tasks (i.e. they can register to be woken up by the
+framework to perform work), and provide services to other modular components.
+
+Any modular component can connect to an agent and access its services (including
+modules, shells, and other agents).
+
+### Environment
+
+An agent is given access to two services provided by the modular framework in
+its incoming namespace:
+
+* `fuchsia.modular.ComponentContext` which gives the agent access to
+ functionality which is shared across components run under the modular
+ framework (e.g. modules, shells, agents).
+* `fuchsia.modular.AgentContext` which gives agents access to agent specific
+ functionality, like creating entity references and scheduling tasks.
+
+An agent is expected to provide two services to the modular framework in its
+outgoing namespace:
+
+* `fuchsia.modular.Agent` which allows the framework to forward connection
+ requests from other components and tell the agent to run tasks.
+* `fuchsia.modular.Lifecycle` which allows the framework to signal the agent
+ to terminate gracefully.
+
+The aforementioned services enable communication between agents and the modular
+framework, but agents can also expose custom FIDL services to components. For a
+more detailed explanation of the mechanism which enables this service exchange
+see Communication Mechanisms below.
+
+### Lifecycle
+
+For most agents, when a component connects to an agent the framework will give
+the component an `AgentController`. When the connecting component drops the
+`AgentController` connection, and there are no outstanding connections, the
+agent will be killed by the framework.
+
+There are some agents for which the `sessionmgr` maintains an `AgentController`,
+and thus the agent remains alive for the duration of the session. These
+"session" agents also get access to `fuchsia.modular.PuppetMaster` in their
+incoming namespace.
+
+### Communication mechanisms
+
+Components can communicate with agents in two different ways: either by
+connecting to a FIDL service exposed by the agent, or over a `MessageQueue`.
+
+Which communication method is appropriate depends on the semantics of the
+messages being passed. FIDL requires both agent and client to be running,
+whereas message queues allow the life cycles of the sender and receiver to be
+different.
+
+#### FIDL Services
+
+The modular framework will forward a `fuchsia.sys.ServiceProvider` request via
+`fuchsia::modular::Agent.Connect` call, and will also provide the agent with an
+identifier for the client which is requesting the service provider.
+
+Any services added to the service provider will be exposed directly to the
+connecting component.
+
+To illustrate this, consider a module connecting to an agent:
+
+The module calls `ConnectToAgent` on its `ComponentContext`, which contains a
+`ServiceProvider` request as well as an `AgentController` request.
+
+The agent controller request is used by the framework to keep the agent alive
+until the agent controller is closed by the client. If more than one client is
+connected to the same agent, the agent will be kept alive until all agent
+controllers have been closed.
+
+The service provider request is forwarded to the agent, along with a string
+which identifies the client connecting to the agent.
+
+#### Message Queues
+
+Messages sent over message queues are untyped, but allow the life cycles of the
+reader and writer to be decoupled. For example, an agent may provide a module
+with a message queue which it can use to send messages to the agent. The agent
+can then register to be woken up when a message is delivered on the queue.
diff --git a/docs/modular/entity.md b/docs/modular/entity.md
index 11a0f7b..4079235 100644
--- a/docs/modular/entity.md
+++ b/docs/modular/entity.md
@@ -1,114 +1,70 @@
-Entities
-====
-> Status: DRAFT
+## Entities
The Fuchsia entity model facilitates information interchange by defining a
-common interface for **describing**, **referencing**, and **accessing** data
-objects (entities) which are shared between components running on the Fuchsia
-platform. It consists of the following major concepts:
+common interface for _describing_, _referencing_, _accessing_, and _mutating_
+data objects (entities) which are shared between components (modules, agents,
+shells) running in the modular framework. It consists of the following major
+concepts:
-* [entities](../../public/lib/entity/fidl/entity.fidl): the data objects
- described by the model
-* entity types: the way different kinds of entities are distinguished
-* [entity references](../../public/lib/entity/fidl/entity_reference_factory.fidl):
- a serializable token that can be used to retrieve an entity handle
-* [entity providers](../../public/lib/entity/fidl/entity_provider.fidl):
- the extensible means by which entities are made available to the system and to
- other components independent of their source
-* [entity resolver](../../public/lib/entity/fidl/entity_resolver.fidl):
- a Fuchsia API for accessing an entity given a reference
+* Entities: the data objects shared between components.
+* Entity references: a serializable token which can be used to retrieve an
+ `Entity` handle.
+* `Entity`: An interface which gives access to a shared data object.
+* `EntityProvider`: the interface which allows agents to expose entities to
+ the system.
+* `EntityResolver`: the Fuchsia API for requesting an `Entity` handle for a
+ given reference.
-Here are some ways entities can be used:
+### Lifecycle
-* copy/paste via the clipboard
-* describing a contact card
-* attaching images and files to an email
-* providing a programmatic interface to create, view, and change calendar
- events independent of any specific calendar provider
-* decoupling presentation components from data sources
-* indicating the focused elements of a story and persisting them across
- restarts
-* enabling the assistant to inspect and manipulate entities present in the
- current context or seen in the past
+The lifecycle of the data backing an `Entity` is controlled by the
+`EntityProvider`. The lifecycle of the `Entity` handle is controlled by
+`sessionmgr`.
-### What are Entities?
+#### Entities owned by Agents
-An entity is an **identifiable** person, place, thing, event, or concept which
-is represented within the Fuchsia platform as a **structured data object**
-which can be **referenced**, **retrieved**, **presented**, **manipulated**, or
-**shared**.
+Agents don't create `Entity` handles directly. Agents connect to the
+`EntityReferenceFactory` which provides the agent with an entity reference in
+exchange for a `cookie`. The entity reference can then be shared with other
+modular components which can use their `EntityResolver` to dereference it into
+an `Entity` interface.
-This use of the term “entity” has parallels in the fields of
-[databases](https://en.wikipedia.org/wiki/fuchsia::modular::Entity%E2%80%93relationship_model),
-[information extraction](https://en.wikipedia.org/wiki/Named_entity), and
-[ontology](https://en.wikipedia.org/wiki/Ontology_(information_science)).
+Calls on that `Entity` interface will then be forwarded to the agent, along with
+the associated cookie.
-Fuchsia entities have the following characteristics:
+The agent is thus responsible for storing and providing the entity data,
+associating it with the correct cookie, and optionally handling requests for
+mutating the entity data.
-* **types**: indicate the representations and intended interpretations of the
- entity’s content, often denoting a particular schema
-* **content**: data which can be retrieved from the entity, often in the form
- of structured properties or binary data as required by the entity’s type
-* **provider** (TODO): the provider of an entity is the component through which
- the content of the entity is accessed
-* **reference**: a token which is used to locate the entity provider from which
- the content of the entity can be retrieved (or modified through actions)
+#### Entities owned by a Story
-Fuchsia entities come in two flavors:
+Modules can create entities explicitly via their `ModuleContext` by providing a
+`fuchsia.mem.Buffer` and an associated type. The framework manages the lifecycle
+of such entities by storing them in the story's record. For this reason, when
+the story is deleted, so is the entity. Agents and modules outside the story can
+dereference the entity so long as the story still exists.
-* **transient entities**: represent objects which exist only at runtime as a
- means of transmitting structured data, examples:
- - a paragraph of text which has been copied to the clipboard and which
- retains no connection to its original source
- - a phone number which has been extracted from content
- - an image which has been captured but not saved anywhere
-* **persistent entities**: represent objects for which a durable record is
- being maintained by an entity provider, examples:
- - an email thread
- - a photo in the camera roll or in the cloud
- - a contact card
- - a calendar event
+#### Entity Resolution
-### How to create an fuchsia::modular::Entity
+This section describes the internals of entity resolution.
-It is currently possible to create *transient entities* by using the
-[`EntityStore`](../services/entity/entity_store.fidl) available in the
-application namespace for both `Modules` and `Agents`.
+`EntityProviderRunner` implements the `fuchsia::modular::EntityResolver`
+interface, and is also responsible for creating entity references by
+implementing the `fuchsia::modular::EntityReferenceFactory` interface. A single
+instance of the `EntityProviderRunner` manages all the entity providers running
+in the system.
-`EntityStore` can create transient Entities from a list of **types** and
-**content** arrays.
+The first step in entity resolution (i.e. the first thing which happens when
+`ResolveEntity` is called) is the runner determines whether the entity is
+provided by an agent or by the modular framework by inspecting the entity
+reference. The runner then asks an `EntityProviderLauncher` to launch the
+appropriate entity provider.
-In Dart:
+If the entity provider is an agent, an `AgentController` is passed to the
+launcher, and the runner keeps the agent controller alive until the client
+closes the `Entity`.
-```dart
-final EntityStoreProxy entityStore = new EntityStoreProxy();
-connectToService(context.environmentServices, entityStore.ctrl);
-final myType = <unique type identifier>;
-final myContent = <uint8 array>;
-entityStore.createEntity([myType], [myContent], (final EntityProxy entity) {
- // Do something with |entity|
-});
-```
-
-In C++:
-TODO
-
-### How to retrieve an fuchsia::modular::Entity
-
-If you have an `EntityReference` (which is available by calling
-`fuchsia::modular::Entity.getReference()` on any `fuchsia::modular::Entity` instance), you can retrieve a handle to
-it by using the `fuchsia::modular::EntityResolver` service available in the application
-namespace. Both `Modules` and `Agents` have this service available.
-
-In Dart:
-
-```dart
-final EntityProxy entity = new EntityProxy();
-final EntityResolverProxy entityResolver = new EntityResolverProxy();
-connectToService(context.environmentServices, entityResolver.ctrl);
-entityResolver.getEntity(entityReference, entity.ctrl);
-// Do something with |entity|
-```
-
-In C++:
-TODO
+Each `Entity` request has an associated `EntityController` which the entity
+runner owns. The `EntityController` owns the `AgentController` if the entity
+provider was an agent, and is responsible for forwarding the entity interface
+methods to the entity provider.
diff --git a/docs/modular/getting_started.md b/docs/modular/getting_started.md
deleted file mode 100644
index da4e421..0000000
--- a/docs/modular/getting_started.md
+++ /dev/null
@@ -1,62 +0,0 @@
-# Getting Started with Modular
-
-## Prerequisities
-
-1. Follow instructions under Development in [Fuchsia Documentation] to get the
- source, setup, build and run Fuchsia.
-2. Follow instructions in the [Ledger User Guide] to setup the Ledger and its
- dependencies. In particular, make sure to do the "minfs setup" as linked
- under the Prerequisites.
-
-To be able to run modules from the Fuchsia command line, you need to select a
-Fuchsia build configuration that does not start `basemgr` and shows a
-graphical session shell right at boot time. You can use for example the
-`test_modular` configuration in `fx set` and build as follows:
-
-``` sh
-fx set x64 --packages peridot/packages/products/test_modular
-fx full-build
-```
-
-If `fx` is not in your `PATH`, you should add `.jiri_root/bin` to your
-`PATH`.
-
-## Running
-
-An application can be run as a module in a story using `dev_session_shell`. For
-example (from [test runner invocation]):
-
-```
-basemgr --test --account_provider=dev_token_manager \
- --base_shell=dev_base_shell --session_shell=dev_session_shell \
- --story_shell=dev_story_shell \
- --session_shell_args=--root_module=parent_child_test_parent_module
-```
-
-`dev_base_shell` is used to log in a dummy user directly without going through
-an authentication dialog. `dev_session_shell` runs the module given to it in
-`--session_shell_args` in a story.
-
-The flags `--session_shell` and `--session_shell_args` are read by `basemgr`.
-The value of `--session_shell` is the application that is run as the session shell.
-The value of `--session_shell_args` is a comma separated list of arguments passed
-to the session shell application. In this example, these arguments are in turn more
-flags. Commas inside the value of such arguments are escaped by backslashes. The
-value of `--root_module` selects the module to run. The value of `--root_link`
-is a JSON representation of the initial data the module is started with.
-
-The user name provided by `dev_base_shell` can be set with `--user`. It is
-used by `basemgr` when opening the Ledger. However, the `--user` parameter
-does not work for `userpicker_base_shell`, because that shell displays a GUI
-to select the user to login.
-
-## Module URLs
-
-Applications are generally referenced by URLs. If the application binary is in a
-location where application manager expects it, e.g. `/pkgfs/packages`, the URL
-can be relative. Otherwise, the URL should be relative with an absolute path, or
-absolute altogether.
-
-[Fuchsia Documentation]: https://fuchsia.googlesource.com/docs/+/master/README.md
-[Ledger User Guide]: ../ledger/user_guide.md
-[test runner invocation]: ../../tests/modular_tests.json
diff --git a/docs/modular/images/run_sequence.png b/docs/modular/images/run_sequence.png
deleted file mode 100644
index 7748c77..0000000
--- a/docs/modular/images/run_sequence.png
+++ /dev/null
Binary files differ
diff --git a/docs/modular/images/services.png b/docs/modular/images/services.png
deleted file mode 100644
index 4f05011..0000000
--- a/docs/modular/images/services.png
+++ /dev/null
Binary files differ
diff --git a/docs/modular/intent.md b/docs/modular/intent.md
index 57f5bad..74be6e2 100644
--- a/docs/modular/intent.md
+++ b/docs/modular/intent.md
@@ -1,48 +1,54 @@
-Intents
-===
+## Intents
-An [`Intent`](../../public/lib/intent/fidl/intent.fidl) is a runtime structure
-for describing a composable action in Fuchsia. `Intents` are produced by
-3rd-party code and platform components.
+An `Intent` is used to instruct a module to perform an action. The intent
+contains the action name, the arguments for the action parameters, and an
+optional handler which explicitly specifies which module is meant to perform the
+action.
-Ultimately, an `Intent` will be handled by a [`Module`](module.md). A process
-called [Module Resolution](module_resolution.md) finds `Modules` capable of
-performing the `action` described by the `Intent`.
+### Declaring Actions
-## Overview
+Modules can declare which actions they handle, and their associated parameters
+in their [module facet](module_facet.md). The modular framework will then index
+the module and treat it as a candidate for any incoming intents which contain
+the specified action, and don't have an explicit handler set.
-`Intents` describe an `action`, its `parameters`, and optionally an explicit
-`handler` for the `action`.
+### Handling Intents
-If an explicit `handler` is not set, then the `Intent` is passed to a
-[Module Resolution](module_resolution.md) process, which returns a set of
-potential `handlers` for the `Intent`.
+When an intent is resolved the framework determines which module instance will
+handle it.
-Once a `handler` has been specified, the data in an `Intent`'s `parameters` is
-exposed to the `handler` via [`Links`](../../public/lib/story/fidl/link.fidl).
+The framework then connects to the module's `fuchsia::modular::IntentHandler`
+service, and calls `HandleIntent()`. The framework will connect to the intent
+handler interface each time a new intent is seen for a particular module
+instance, and intents can be sent to modules which are already running. Modules
+are expected to handle the transition between different intents gracefully.
-## Examples
+### Example
-### Creating an Intent with an explicit handler
+To illustrate the intended use of intents, consider the following fictional
+example: a new story has been created with a module displaying a list of
+restaurants and the module wants to show directions to the currently selected
+restaurant.
-```
-// Create an Intent parameter with an entity representing the selectable
-// contacts.
-IntentParameterData parameter_data;
-parameter_data.set_entity_reference(contacts_list_entity_ref);
+The restaurant module creates an intent with a `com.fuchsia.navigate` action
+with two parameters `start` and `end`, both of type `com.fuchsia.geolocation`
+and passes it to the modular framework via `ModuleContext.AddModuleToStory`.
-IntentParameter parameter;
-parameter.name = "contacts";
-parameter.data = parameter_data;
+At this point, the framework will search for a module which has declared support
+for the `com.fuchsia.navigate` action. Once such a module is found, it is added
+to the story and started. The framework then connects to the started module's
+`IntentHandler` service and provides it with the intent.
-Intent intent;
-intent.handler = url_to_contacts_picker_module;
-intent.action = "com.google.fuchsia.pick-contacts";
-intent.parameters = { parameter };
+At this point, the restaurant list module's selected restaurant changes. It
+again creates an intent, with the same action as before but with new location
+arguments and calls `ModuleContext.AddModuleToStory`.
-module_context.StartModule("contacts-picker", intent ...);
-```
+The framework now knows there is already a module instance running (in this case
+`AddModuleToStory` uses the `name` parameter to identify module instances)o
+explicitly specify a which can handle the given action, and connects to its
+`IntentHandler` interface and provides it with the new intent. The navigation
+module can then update its UI to display directions to the new restaurant.
-The framework will find the `handler` (i.e. the contacts picker module), and
-make sure that it sees the provided contacts list entity under a link called
-`contacts` (as specified by the `IntentParameter`'s name).
+If the restaurant module wanted a specific module (e.g. `Fuchsia Maps`) to
+handle the intent, it would set the `Intent.handler` to the component URL for
+the module.
diff --git a/docs/modular/manifests/entity_type.md b/docs/modular/manifests/entity_type.md
deleted file mode 100644
index 6bf3ce4..0000000
--- a/docs/modular/manifests/entity_type.md
+++ /dev/null
@@ -1,45 +0,0 @@
-fuchsia::modular::Entity Types
-===
-> Status: DRAFT
->
-> This is a stand-in for a future schematic metadata system for Entities. For now,
-> it is used to specify schemas for schematic content in the cases where that
-> is relevant to clients creating Entities.
-
-In Fuchsia, data sharing between system and application components is a central
-part of enabling interesting and powerful user experiences. To promote
-interoperability, Fuchsia includes an [`fuchsia::modular::Entity`](../entity.md) runtime primitive, which
-represents structured data. An `fuchsia::modular::Entity` can represent data of multiple `types`.
-A `type` indicates both the semantics of the data as access patterns.
-
-fuchsia::modular::Entity types and, if relevant, their schemas for schematic data, are published and
-public to everyone.
-
-## Defining fuchsia::modular::Entity types in a JSON file
-
-> TODO(thatguy): Add information about where these schemas are discoverable.
-
-fuchsia::modular::Entity types and schemas are defined in file with a JSON-encoded list of dictionaries with the following format (JSON schema [available
-here](../src/package_manager/metadata_schemas/entity_type.json)):
-
-```javascript
-[
- {
- "name": "https://types.fuchsia.io/FirstType",
- "schema": "path/to/schema.json"
- },
- {
- "name": "https://types.fuchsia.io/SecondType",
- "schema": ...
- },
- ...
-]
-```
-
-`name` is a string identifier that must be unqiue within this metadata
-file.
-
-`schema` is a path to a file within the package that contains a [JSON
-Schema](http://json-schema.org/).
-
-Any number of `fuchsia::modular::Entity` types can be defined in one file.
diff --git a/docs/modular/manifests/module.md b/docs/modular/manifests/module.md
deleted file mode 100644
index 9f6f17b..0000000
--- a/docs/modular/manifests/module.md
+++ /dev/null
@@ -1,158 +0,0 @@
-Module Metadata File
-===
-> Status: DRAFT
-
-A Module metadata file defines the runtime capabilities of a single `Module`
-(**TODO: link**). A Module expresses its capabilities by declaring the different intents it is able to handle (**TODO**: link to action/action template doc).
-
-The file is part of a Fuchsia package (**TODO: link**), is named `module` and
-placed within the `meta/` of the package.
-
-The `module` file contents are a JSON-encoded object (JSON schema [available
-here](../../../build/module_manifest_schema.json)) that defines a
-single action implementation.
-
-## Example module `manifest.json` file
-
-Following are two sample `manifest.json` files. Each describes a `Module` being
-able to handle particular intents (`action` and associated `parameters`s) using
-`intent_filters`.
-
-```javascript
-{
- "binary": "bin/myPersonPreviewer",
- "suggestion_headline": "See details about person",
- "intent_filters": [
- {
- "action": "com.google.fuchsia.preview.v1",
- "parameters": [
- {
- "name": "entityToPreview",
- "type": "https://fuchsia.instagram.com/types/Friend"
- }
- ],
- }
- ]
- "composition_pattern": "ticker"
-}
-```
-```javascript
-{
- "binary": "bin/myContactPicker",
- "suggestion_headline": "Pick an instagram friend",
- "intent_filters": [
- {
- "action": "com.google.fuchsia.pick.v1",
- "parameters": [
- {
- "name": "source",
- "type": "https://fuchsia.instagram.com/types/FriendRepository"
- },
- {
- "name": "picked",
- "type": "https://fuchsia.instagram.com/types/Friend"
- }
- ]
- }
- ]
-}
-```
-
-## Detailed description
-
-Let's break down one of the examples above and go through the properties in detail.
-
-### Attributes that define behavior
-
-#### binary
-
-```javascript
-"binary": "bin/myPreviewer",
-```
-
-Specifies the relative path from the root of the package where the Module
-executable file can be found. Different action implementations within the same
-package can share a single `binary`.
-
-#### suggestion_headline
-
-> TODO(thatguy): If we keep this, expand it to support
-> templating based on the entity args.
-
-```javascript
-"suggestion_headline": "See details about person",
-```
-
-The `suggestion_headline` attribute provides human-readable
-text. It will be used if this `Module` is suggested for inclusion
-in the current Story.
-
-#### intent_filters
-
-```javascript
-"intent_filters": [
- {
- "action": "com.google.fuchsia.preview.v1",
- "parameters": [
- {
- "name": "entityToPreview",
- "type": "https://fuchsia.instagram.com/types/Friend"
- }
- ]
- }
-]
-```
-> NOTE: The exactly format of the action attribute is likely to evolve.
-The `intent_filters` attributes identifiers the different intents this Module is
-able to handle. Each intent consists of an `action` and its associated
-`parameters`. An `action` dictates a semantic function this Module implements,
-as well as the role of each of its `parameters`.
-
-The `action` must match an `action` name in an associated
-[`meta/action_template`](action_template.md) file.
-
-> TODO(thatguy): Add information about where actions are discoverable.
-
-In the [action template](action_template.md), the parameters are given names but not
-assigned concrete fuchsia::modular::Entity types (**TODO** link). Here, we constrain this
-action implementation to operate on a specific set of [fuchsia::modular::Entity](../entity.md)
-types.
-
-Each parameter in the action template gets an entry in `parameter_constraints`. Each entry
-is made up of the following fields:
-
-* `name`: this is the name of the parameter given in the [action template](action_template.md)
-* `type`: an [fuchsia::modular::Entity](../entity.md) types.
-
- > TODO(thatguy): Add information about where entity types & schemas are discoverable.
-
- > TODO(thatguy): The semantics of `type` doesn't make a lot of sense for *output*
- or maybe *input/output* parameters.
-
-At runtime, this `Module` will communicate with its parent (the invoker of the
-`Module`) through multiple [`fuchsia::modular::Link`](../../services/story/link.fidl) interfaces. The `fuchsia::modular::Link` enforces the
-typing described here, making any attempt to write an `fuchsia::modular::Entity` with an
-incompatible type an error.
-
-#### composition_pattern
-
-```javascript
-"composition_pattern": "ticker",
-```
-Specifies the composition pattern with which the module will shown with existing module(s) in
-the story. For example, the ticker pattern described above gives a signal to the story shell that
-the module should be placed below another module that it may share a link with.
-
-Currently supported patterns:
- ticker: Shown at the bottom of the screen underneath another module.
- comments-right: Shown to the right of another module.
-
-> NOTE: the set of the patterns supported and their names will likely evolve with time.
-
-#### outgoing services
-
-TODO
-
-### Attributes that define display constraints
-
-TODO
diff --git a/docs/modular/modular_runtime.graffle b/docs/modular/modular_runtime.graffle
deleted file mode 100644
index c47bd4c..0000000
--- a/docs/modular/modular_runtime.graffle
+++ /dev/null
Binary files differ
diff --git a/docs/modular/module.md b/docs/modular/module.md
index 123e159..4d16564 100644
--- a/docs/modular/module.md
+++ b/docs/modular/module.md
@@ -1,18 +1,42 @@
-Module
-======
+## Modules
-A module is an application that implements the Module interface, whose lifecycle
-is tightly bound to the story in which it was started and may implement a UI. A
-module is started in a story by another module or by the system from which it
-receives a fuchsia::modular::Link service . It can also receive / provide other services via
-ServiceProviders. A module is terminated if the story in which it is running
-becomes inactive, or the module that started it decides to terminate it or it
-decides to terminate itself. A module can start other modules, create,
-send / receive messages and call FIDL interfaces.
+A `Module` is a component which displays UI and runs as part of a `Story`.
-## See also:
-[Module](../services/module/module.fidl)
-[fuchsia::modular::ModuleContext](../services/module/module_context.fidl) (formerly Story)
-[fuchsia::modular::ModuleController](../services/module/module_controller.fidl)
-[fuchsia::modular::Link](../services/story/link.fidl)
-[fuchsia::modular::MessageQueue](../services/component/message_queue.fidl)
+Multiple modules can be composed into a single story, and modules can add other
+modules to the story they are part of. Module's can either embed other modules
+within their own content, or they can delegate visual composition to the
+`StoryShell`.
+
+### Environment
+
+A module is given access to two services provided by the modular framework in
+its incoming namespace:
+
+* `fuchsia.modular.ComponentContext` which gives the agent access to
+ functionality which is shared across components run under the modular
+ framework (e.g. modules, shells, agents).
+* `fuchsia.modular.ModuleContext` which gives modules access to module
+ specific functionality, like adding other modules to its story and creating
+ entities.
+
+A module is expected to provide two services to the modular framework in its
+outgoing namespace:
+
+* `fuchsia.ui.app.ViewProvider` which is used to display the module's UI.
+* `fuchsia.modular.Lifecycle` which allows the framework to signal the module
+ to terminate gracefully.
+* `fuchsia.modular.IntentHandler` which allows the framework to send
+ [intents](intent.md) to the module.
+
+### Lifecycle
+
+A module's lifecycle is bound to the lifecycle of the story it is part of. In
+addition, a given module can have multiple running instances in a single story.
+
+When a module starts another module it is given a module controller which it can
+use to control the lifecycle of the started module.
+
+### Communication Mechanisms
+
+Modules communicate with other modules via intents and entities, and with agents
+via FIDL and message queues.
diff --git a/docs/modular/module_facet.md b/docs/modular/module_facet.md
index 527b855..9657e2d 100644
--- a/docs/modular/module_facet.md
+++ b/docs/modular/module_facet.md
@@ -1,8 +1,8 @@
# Module Facet
Modules declare their run-time capabilities (e.g. which Intent actions they
-handle) in the module facet of their [component
-manifest][component-manifest] (i.e. their `.cmx` file).
+handle) in the module facet of their [component manifest][component-manifest]
+(i.e. their `.cmx` file).
## What is a facet?
@@ -11,7 +11,8 @@
other parts of Fuchsia. The Modular framework defines a `fuchsia.module` facet
which module authors use to define module specific properties.
-This document describes how to declare a module facet in your component manifest.
+This document describes how to declare a module facet in your component
+manifest.
## Example
@@ -40,7 +41,6 @@
}
```
-
This module can be launched using an Intent with the action
`com.google.fuchsia.preview.v1` action, and a `entityToPreview` parameter of
type `https://fuchsia.com/types/Friend`.
@@ -50,66 +50,69 @@
The module facet is defined under the `fuchsia.module` facet in a component
manifest. See [example](#example).
-* `@version` **unsigned integer** *(required)*
- - Describes the version of the module facet. The fields below indicate which
- minimum `@version` they require.
- - **example**: `2`
-* `composition_pattern`: **string** *(optional)*
- - **minimum `@version`**: 1
- - **possible values:**
- * `ticker`: Show the module at the bottom of the screen underneath another
- module.
- * `comments-right`: show the module to the right of other modules.
- - **example**: `"ticker"`
- - Specifies the compositional pattern that will be used by the story shell to
- display this module along-side other modules in the story. For example, the
- ticker pattern gives a signal to the story shell that the module should be
- placed below another module that it may share a link with.
-* `suggestion_headline`: **string** *(optional)*
- - **minimum `@version`**: 2
- - **possible values**: UTF-8 string
- - **example**: `"See details about this person"`
- - A human-readable string that may be used when suggesting this Module.
-* `placeholder_color`: **string** *(optional)*
- - **minimum `@version`**: 2
- - **possible values**: hex color code, leading with a hashtag (`#`)
- - **example**: `"#ff00ff"`
- - Defines the color of the placeholder widget used while the module loads.
-* `intent_filters`: **IntentFilter[]** *(optional)*
- - **minimum `@version`**: 2
- - **possible values**: JSON list of [IntentFilter](#IntentFilter)
- - **example**: See [example](#example).
- - A list of different Intent types this Module is able to handle. An action
- dictates a semantic function this Module implements, as well as the role of
- each of its parameters. When resolving an intent to a module, the intent
- resolver uses an index of these intent filter lists to determine which
- modules can handle an intent.
+* `@version` **unsigned integer** *(required)*
+ - Describes the version of the module facet. The fields below indicate
+ which minimum `@version` they require.
+ - **example**: `2`
+* `composition_pattern`: **string** *(optional)*
+ - **minimum `@version`**: 1
+ - **possible values:**
+ * `ticker`: Show the module at the bottom of the screen underneath another
+ module.
+ * `comments-right`: show the module to the right of other modules.
+ - **example**: `"ticker"`
+ - Specifies the compositional pattern that will be used by the story shell
+ to display this module along-side other modules in the story. For
+ example, the ticker pattern gives a signal to the story shell that the
+ module should be placed below another module that it may share a link
+ with.
+* `suggestion_headline`: **string** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: UTF-8 string
+ - **example**: `"See details about this person"`
+ - A human-readable string that may be used when suggesting this Module.
+* `placeholder_color`: **string** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: hex color code, leading with a hashtag (`#`)
+ - **example**: `"#ff00ff"`
+ - Defines the color of the placeholder widget used while the module loads.
+* `intent_filters`: **IntentFilter[]** *(optional)*
+ - **minimum `@version`**: 2
+ - **possible values**: JSON list of [IntentFilter](#IntentFilter)
+ - **example**: See [example](#example).
+ - A list of different Intent types this Module is able to handle. An
+ action dictates a semantic function this Module implements, as well as
+ the role of each of its parameters. When resolving an intent to a
+ module, the intent resolver uses an index of these intent filter lists
+ to determine which modules can handle an intent.
### IntentFilter
+
`IntentFilter` is a JSON object used to describe an intent type that a module is
able to handle. The following describes the fields of the IntentFilter JSON
object:
-* `action`: **string** *(required)*
- - **minimum `@version`**: 2
- - **possible values**: ASCII string
- - The action this module is able to handle.
-* `parameters`: **ParameterConstraint[]** *(required)*
- - **minimum `@version`**: 2
- - **possible values**: JSON List of
- [ParameterConstraint](#ParameterConstraint)
- - Describes the names and types of the parameters required to execute the
- specified action. Parameters are typically passed in as Entities.
+* `action`: **string** *(required)*
+ - **minimum `@version`**: 2
+ - **possible values**: ASCII string
+ - The action this module is able to handle.
+* `parameters`: **ParameterConstraint[]** *(required)*
+ - **minimum `@version`**: 2
+ - **possible values**: JSON List of
+ [ParameterConstraint](#ParameterConstraint)
+ - Describes the names and types of the parameters required to execute the
+ specified action. Parameters are typically passed in as Entities.
### ParameterConstraint
+
`ParameterConstraint` describes a particular intent parameter's name, and it's
acceptable type.
-* `name`: **string** *(required)*
- - **minimum `@version`**: 2
-* `type`: **string** *(required)*
- - **minimum `@version`**: 2
- - Type that is valid for this parameter.
+* `name`: **string** *(required)*
+ - **minimum `@version`**: 2
+* `type`: **string** *(required)*
+ - **minimum `@version`**: 2
+ - Type that is valid for this parameter.
See [example](#example).
diff --git a/docs/modular/module_resolution.md b/docs/modular/module_resolution.md
deleted file mode 100644
index df1adf0..0000000
--- a/docs/modular/module_resolution.md
+++ /dev/null
@@ -1,50 +0,0 @@
-Module Resolution
-===
-
-Resolution is the process by which a Fuchsia [`fuchsia::modular::Intent`](intent.md), which
-represents an abstract or loosely specified action, is expanded into a set of
-concrete Module implementations for execution and ranked by relevance to a
-provided context.
-
-Resolution is provided indirectly by the Modular Framework through calls on
-either the [`fuchsia::modular::ModuleContext`](../../public/lib/module/fidl/module_context.fidl)
-(for Module clients) or the
-[`fuchsia::modular::StoryController`](../../public/lib/story/fidl/story_controller.fidl) (for
-privileged platform clients). Specifically, clients would call either
-`fuchsia::modular::ModuleContext.StartModule()` or `fuchsia::modular::StoryController.fuchsia::modular::AddModule()`.
-
-This document outlines what happens behind the scenes of those two calls.
-
-## The fuchsia::modular::ModuleResolver
-The
-[`fuchsia::modular::ModuleResolver`](../../public/lib/module_resolver/fidl/module_resolver.fidl)
-is the FIDL service that provides Module Resolution to its clients. It is only
-accessible directly by the Framework and other privileged platform components.
-Nonetheless, the process is fundamental to the user experience in Fuchsia and
-warrants its own public documentation.
-
-### Inputs
-TODO
-
-* A `fuchsia::modular::Intent`: defines `Module` constraints based on desired action and/or
- instances of runtime data.
-* A `ScoringInfo` struct: informs the fuchsia::modular::ModuleResolver on how to score and rank
- the results, including the scope of context signals that may affect ranking.
-
-### Outputs
-TODO
-
-A ranked list of `fuchsia::modular::ModuleResolverResult`. Contains all the data necessary to
-initialize a specific Module instance backed by an executable.
-
-
-### Resolution Steps
-
-#### 1. Noun translation/extraction
-TODO
-#### 2. Retrieval
-TODO
-#### 3. Filtering
-TODO
-#### 4. Ranking
-TODO
diff --git a/docs/modular/multiple_qemu_instances.md b/docs/modular/multiple_qemu_instances.md
deleted file mode 100644
index 346f96c..0000000
--- a/docs/modular/multiple_qemu_instances.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Running multiple QEMU instances w/ network
-
-Running Fuchsia on multiple instances of QEMU on the same machine with network
-is useful for developing multi-device features, especially with ledger
-synchronization between them.
-
-## Instructions for running two QEMU instances w/ network and ledger
-
-These instructions are for linux hosts only. Running one Qemu on MacOS is slow
-enough so it's probably useless to try to run two.
-
-There should be a way to just use
-the
-[start-dhcp-server.sh](https://fuchsia.googlesource.com/scripts/+/master/start-dhcp-server.sh) twice,
-but I (mesch) could not get it to work. The difficulty is that each dnsmasq
-instance, even if it's confined to serve DHCP on only one interface, still
-serves DNS on *all* interfaces.
-
-We also set up persistent storage for the ledger. Notice, however, that with
-ledger sync state is preserved in the cloud sync location for the ledger, so
-it's usually not lost when the device is rebooted. The only thing persistent
-storage buys is to preserve the ledger cloud sync configuration.
-
-### Prerequisites on host
-
-1. Create two [tap], `qemu0` and `qemu1` (both are separate from the default
-value `qemu`, to distiguish the qemu instances started here). The values are
-passed to the `-I` command line option below:
-
-```
-sudo tunctl -u $USER -t qemu0
-sudo tunctl -u $USER -t qemu1
-```
-
-2. Choose two *different* IPv4 subnets to use for `qemu0` and `qemu1`, say
-`192.168.7.0` and `192.168.8.0` (both are separate from the default for either
-qemu or acer, for the same reason as above):
-
-```
-sudo ifconfig qemu0 192.168.7.1 up
-sudo ifconfig qemu1 192.168.8.1 up
-```
-
-3. Configure dnsmasq to serve DHCP on these two devices. Add this to
-`/etc/dnsmasq.conf`:
-
-```
-interface=qemu0
-dhcp-range=qemu0,192.168.7.50,192.168.7.150,24h
-
-interface=qemu1
-dhcp-range=qemu1,192.168.8.50,192.168.8.150,24h
-```
-
-4. Restart `dnsmasq` to pick up the configuration change:
-
-```
-sudo /etc/init.d/dnsmasq stop
-sudo /etc/init.d/dnsmasq start
-```
-
-
-5. Setup NAT:
-
-```
-echo 1 > /proc/sys/net/ipv4/ip_forward
-iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
-iptables -A FORWARD -i eth0 -o qemu0 -m state --state RELATED,ESTABLISHED -j ACCEPT
-iptables -A FORWARD -i qemu0 -o eth0 -j ACCEPT
-iptables -A FORWARD -i eth0 -o qemu1 -m state --state RELATED,ESTABLISHED -j ACCEPT
-iptables -A FORWARD -i qemu1 -o eth0 -j ACCEPT
-```
-
-6. Create two [minfs] block devices one for each instance. Call them `blk0.bin`
-and `blk1.bin`.
-
-### Command line on host
-
-Start two qemu instances running fuchsia/zircon.
-
-```
-$ scripts/run-zircon-x64 -N -I qemu0 -x out/debug-x64/user.bootfs -g -- -hda blk0.bin
-$ scripts/run-zircon-x64 -N -I qemu1 -x out/debug-x64/user.bootfs -g -- -hda blk1.bin
-```
-
-### Prerequisites on fuchsia
-
-Each fuchsia instance needs to be set up once:
-
-1. For the [minfs] block devices create partitions and filesystems and configure
-them to be mounted to boot.
-
-2. Configure [cloudsync] to point to the same cloud sync location.
-
-
-### Command line on fuchsia
-
-To run one story and watch it sync between devices, for example the
-`example_todo_story`, do something like this:
-
-1. Start a todo story on one side:
-
-```
-basemgr --session_shell=dev_session_shell --session_shell_args=--root_module=example_todo_story
-
-```
-
-2. Retrieve the story id from the log output, then start the same story on the other side:
-
-```
-basemgr --session_shell=dev_session_shell --session_shell_args='--story_id=CmfpuRWuBo'
-
-```
-
-You can also just run the default session shell and restart stories from the timeline.
-
-[qemu]: https://fuchsia.googlesource.com/zircon/+/master/docs/qemu.md "QEMU"
-[fuchsia]: https://fuchsia.googlesource.com/docs/+/HEAD/getting_started.md#Enabling-Network "Fuchsia Network"
-[tap]: https://fuchsia.googlesource.com/zircon/+/master/docs/qemu.md#Enabling-Networking-under-QEMU-x86_64-only "TAP interfaces"
-[cloudsync]: https://fuchsia.googlesource.com/ledger/+/HEAD/docs/user_guide.md#Cloud-Sync "Cloud Sync in Ledger"
-[minfs]: https://fuchsia.googlesource.com/zircon/+/master/docs/minfs.md
diff --git a/docs/modular/overview.md b/docs/modular/overview.md
new file mode 100644
index 0000000..4672439
--- /dev/null
+++ b/docs/modular/overview.md
@@ -0,0 +1,43 @@
+## Overview
+
+Modular is the application framework for Fuchsia. It manages user experiences by
+composing UI, data, and users from a diverse set of components into logical and
+visual containers called Stories.
+
+The framework defines classes of components to extend user experiences and
+provides software primitives for component composition, communication, task
+delegation, state management and data sharing.
+
+### Requirements to use Modular
+
+Modular supports software written in any language (e.g. Flutter, C++) for any
+Fuchsia supported runtime, as long as it is a Fuchsia Component.
+
+The Modular Framework communicates with components it launches via FIDL, the
+standard IPC mechanism for Fuchsia.
+
+### Extension Points
+
+The framework defines several different classes of components which can be
+implemented by developers to extend the behavior of user experiences:
+
+1. [Modules](module.md) are components which display UI and are visually
+ composed in a [Story](story.md).
+1. [Agents](agent.md) are components which run in the background to provide
+ services and data to Modules and other Agents.
+1. [Shells](shell.md) manage system UI and mediate user interactions.
+1. [EntityProviders](entity.md) are components which provide access to data
+ object (entities) which are shared between components running in modular.
+
+### `basemgr` and `sessionmgr`
+
+After Fuchsia device startup, `basemgr` and `sessionmgr` are processes that
+provide session management, component lifecycle management and state management.
+
+* [`basemgr`](basemgr.md) is responsible for user authentication and
+ authorization. It leverages the Base Shell to present UI.
+
+* [`sessionmgr`](sessionmgr.md) is responsible for the lifecycle of Stories,
+ Modules and Agents, as well as service and state coordination between them.
+ It leverages Session and Story Shells to manage the visual composition of
+ these components.
diff --git a/docs/modular/run_sequence.md b/docs/modular/run_sequence.md
deleted file mode 100644
index 9620d83..0000000
--- a/docs/modular/run_sequence.md
+++ /dev/null
@@ -1,5 +0,0 @@
-A boot sequence diagram that shows the order in which various Framework
-components get started. It also shows the `Environment` in which a
-particular component is run.
-
-
diff --git a/docs/modular/services.md b/docs/modular/services.md
deleted file mode 100644
index c9cc0ff..0000000
--- a/docs/modular/services.md
+++ /dev/null
@@ -1,8 +0,0 @@
-A boot sequence diagram that shows the order in which various framework
-components get started. It also shows the `Environment` in which a
-particular component is run.
-
-A diagram that shows the various FIDL services implemented by the Framework and
-the C++ classes that implement them.
-
-
diff --git a/docs/modular/shell.md b/docs/modular/shell.md
new file mode 100644
index 0000000..6452ffb
--- /dev/null
+++ b/docs/modular/shell.md
@@ -0,0 +1,40 @@
+## Shells
+
+Shells are components which are responsible for composing UI. There are three
+shells:
+
+* `BaseShell` displays UI associated with a device, prior to a session being
+ started.
+* `SessionShell` displays the UI associated with a given session (e.g. list of
+ stories, settings UI).
+* `StoryShell` displays a single story (i.e. the composition of the modules in
+ a story, each story gets its own `StoryShell` instance).
+
+### Environment
+
+A shell is given access to two services provided by the modular framework in its
+incoming namespace:
+
+* `fuchsia.modular.ComponentContext` gives the agent access to functionality
+ which is shared across components run under the modular framework (e.g.
+ modules, shells, agents).
+* `fuchsia.modular.[Base,Session,Story]ShellContext` gives access to shell
+ specific functionality for each type of shell, respectively.
+
+A shell is expected to provide two services to the modular framework in its
+outgoing namespace:
+
+* `fuchsia.modular.[Base,Session,Story]Shell` the modular framework uses to
+ communicate requests to display UI.
+* `fuchsia.modular.Lifecycle` allows the framework to signal the shell to
+ terminate gracefully.
+
+### Lifecycle
+
+The three shells have varying lifecycles:
+
+* `BaseShell` runs between the time `basemgr` starts up until a session has
+ been established, and on demand thereafter to faciliate authentication
+ requests.
+* `SessionShell` runs for the duration of a session.
+* `StoryShell` runs while its associated story is running.
diff --git a/docs/modular/story.md b/docs/modular/story.md
index 185cf47..ad3e8e7 100644
--- a/docs/modular/story.md
+++ b/docs/modular/story.md
@@ -1,17 +1,16 @@
-Story
-=====
+## Stories
-A story is a logical container for a root application along with associated
-data. An instance of a story can be created, deleted, started and stopped by the
-system in response to user actions. Creating a new story instance creates an
-entry in the user's ledger which stores the data associated with this story
-instance; deleting a story instance deletes the associated data. Starting a
-story instance runs the root application; which may start other applications. If
-the root application is a module, it can start other modules and access / modify
-data associated with the story instance (via links). The root application must
-also implement the view associated with this story which might embed views from
-other applications / modules.
+A story is a logical container for composing a set of modules.
-## See also:
-[fuchsia::modular::StoryProvider](../services/story/story_provider.fidl)
-[fuchsia::modular::StoryController](../services/story/story_controller.fidl)
+Stories and their associated state are stored in the user's Ledger.
+
+### Presentation
+
+The modular framework uses the `fuchsia.modular.StoryShell` interface to display
+the UI for stories.
+
+### Lifecycle
+
+Stories can be created, deleted, started, and stopped. Created and deleted refer
+to the existence of the story in the ledger, whereas started and stopped refer
+to whether or not the story and its associated modules are currently running.
