bootstrap

This directory is where an agent starts when it has been handed a repository and knows nothing else about it. Everything here is a file to read: text (.md), data (.json) and diagrams (.bpmn). Nothing here is a program, so you need nothing installed to use it.

A capitalized word on this page is a defined term. It links to its definition the first time it appears, and [src] beside it opens the schema that defines it. Every definition is drawn on one page, schemas/README.md, from one file, schemas/graph.schema.json.

Contents

This section was generated by bootstrap-tools — scripts/readme-sections.ts, from this README's own headings (section kg:toc). Do not edit it here; edit outside the markers, or change what it is generated from.

• What you are setting up
• Who takes part
• User story
• Steps
• Functional Requirements
• Reading it on the web
• Every file here

What you are setting up

A Knowledge Graph (src) is information kept as files in a repository: things, and the named relations between them. One file at its root, <name>.json, declares it. That file gives its name and lists its Subgraphs (src), the named directories it is divided into.

A Harness (src) is what you use to work with a Knowledge Graph. A Harness is a Knowledge Graph too, declared the same way. This directory is the first Harness, bootstrap, declared by bootstrap.json.

Setting up a repository means instantiating one or more different kinds of Knowledge Graph Harness on the data in the repository. A person chooses which ones, and the choice is hard to undo.

Who takes part

An Actor (src) is a person, an agent or a program. Each Actor takes a Role (src), and the four Roles here are declared in scenarios/roles.json:

The same four, as scenarios/roles.json defines them, with every name each goes by: other names in use today, and former names with the day each was retired, so a name met in older text still leads to the right one.

This section was generated by bootstrap-tools — scripts/readme-sections.ts, from the Roles the instance declares (section kg:roles). Do not edit it here; edit outside the markers, or change what it is generated from.

As the Bootstrapping Agent you have no Harness yet, so you have no tools (programs to call): a Harness defines those, and bootstrap does not. If a step seems to need one, it belongs to the Harness you are about to set up, not to this one.

User story

As the Bootstrapping Agent, I want to set up the repository I was handed as the Harness the Requestor chooses, so that everything added to it later is built on the right Harness.

The story ends in one of two ways, and both are acceptable: the Harness is set up, or the reason it could not be is recorded.

Steps

The steps are drawn as a Process (src), initialize-harness.bpmn. It is the only Process you start; every other one is called from a step. Each step names the Skill (src) to read and the Functional Requirement it must meet (see the next section).

 1  Learn how to open files here
 |
 2  Determine the Harness and repositories  --- ask --->  the Requestor chooses one Harness
 |
 3  Check each repository  --- already this Harness? --->  go to 7
 |                         --- already another one? --->  record it and stop
 4  Record that you are starting
 |
 5  Follow the chosen Harness's own instructions
 |
 6  Leave a README at the repository's root, if it has none
 |
 7  Make sure every step the declarations name is done  --- only a person can? ---> ask
      first: the JSON Schemas and JSON-LD at the IRIs they name
 |
    Harness installed, every step reported: done, not done, could not determine, or stated

    At any step: something cannot be found or read  --->  record it and stop
    Whenever a person must decide or act  --->  the one human-agent discussion
      (first: say which process, as which role, in what context;
       what you cannot say is the first thing you ask)

The same steps, and the Processes they start, as the diagrams themselves:

This section was generated by bootstrap-tools — scripts/readme-sections.ts, from the Process diagrams the declaration lists (section kg:processes). Do not edit it here; edit outside the markers, or change what it is generated from.

Initialize a harness: processes/initialize-harness.bpmn, the one you start; it calls "Determine the harness and repositories", "Log a message" and "Complete initialization".

Complete initialization: processes/complete-initialization.bpmn, started from "Initialize a harness"; it calls "Human–agent discussion" and "Log a message".

Determine the harness and repositories: processes/discussion.bpmn, started from "Initialize a harness"; it calls "Human–agent discussion".

Human–agent discussion: processes/human-agent-discussion.bpmn, a reusable sub-process, started from "Complete initialization" and "Determine the harness and repositories".

Log a message: processes/log-message.bpmn, a reusable sub-process, started from "Complete initialization" and "Initialize a harness".

1. Learn how to open files here. Read skills/bootstrap-kg-navigation.md. Opening files is all you can do (Functional Requirement 1, FR-1).

2. Determine the Harness and repositories. List the Harnesses the repository could become, and the repositories it could be set up in. Then ask the Requestor for one Harness and its repositories (FR-3), through the one reusable discussion (FR-9). Read skills/confirm-harness.md for what to ask, and skills/human-agent-discussion.md for how. This step is done when the answer is written down as a document that matches schemas/discussion.output.schema.json.

3. Check each repository. If its root already holds a declaration, <name>.json, it is already set up (FR-5). If it is the Harness the Requestor chose, go straight to step 7; if it is another, record that and stop.

4. Record that you are starting. Read skills/log-message.md.

5. Follow the chosen Harness's own instructions. Every Harness keeps them at the same path (FR-4):

   <name>/docs/bootstrap/initialization.md
   

   Here <name> is the name the Requestor chose, as it appears in that Harness's declaration, <name>.json.

6. Leave a README at the repository's root, if it has none (FR-8). Read skills/root-readme.md.

7. Make sure every step is done (FR-10). The steps are the ones the declarations name. First, and primary: the Harness's JSON Schemas and JSON-LD documents are published at the IRIs they name (FR-11; read skills/publish-documents.md). Then the declared directories and files, the README and the sections it opts into, each needed Harness's own instructions, and the site on GitHub Pages, which is how the documents get to their addresses. Check each one before doing anything, do what you can, and ask the person for what only they can do. Read skills/initialization-steps.md and, for the site, skills/publish-site.md. Where a toolset that reads these declarations is available, it may perform the same checks.

If anything cannot be found or read along the way, record what failed (step 4's Skill) and stop (FR-6).

Functional Requirements

A Functional Requirement is a rule the steps must meet. Each has a number, so a step can name it: Functional Requirement 1 is FR-1.

Reading it on the web

Every README here, the root's first and then each directory's, is also one page with a table of contents at https://litlfred.github.io/bootstrap/README.html, beside every file as it sits here; the site's root address redirects to it. The page is built by a separate toolset, from these files, and published from outside this repository: nothing here builds or publishes it, and no step in this README needs it (FR-7). The site is also the first repository to go through its own step 7: skills/publish-site.md.

Every file here

Grouped by directory, each described from the file itself. "Used by" names the Process that reads a file, where a diagram says so.

This section was generated by bootstrap-tools — scripts/readme-sections.ts, from the declared directories and each file in them (section kg:files). Do not edit it here; edit outside the markers, or change what it is generated from.

At the top

skills/

schemas/: The schemas bootstrap is checked against: graph.schema.json, the shape of a declaration and the definition of every term bootstrap uses; and the input and…

scenarios/: bootstrap's four Roles: Bootstrapping Agent, Requestor, Knowledge Graph Data Store and Logger.

processes/: bootstrap's Processes: initialize-harness.bpmn, the only one an Actor starts; discussion.bpmn, which it calls to determine the harness and repositories;…

models/: Which languages a model is good at, and whether anybody checked.