Add stub nomenclature doc

README.md

@@ -1,18 +1,63 @@
 diachron
 
+## Introduction
+
+Is your answer to some of these questions "yes"?  If so, you might like
+diachron.  (When it comes to that dev/test/prod one, hear us out first, ok?)
+
+- Do you want to share a lot of backend and frontend code?
+
+- Are you tired of your web stack breaking when you blink too hard?
+
+- Have you read [Taking PHP
+  Seriously](https://slack.engineering/taking-php-seriously/) and wish you had
+  something similar for Typescript?
+
+- Do you think that ORMs are not all that, and you had first class unmediated
+  access to your database?  And do you think that database agnosticism is
+  overrated?
+
+-- Do you think dev/testing/prod distinctions are a bad idea?  (Hear us out on
+  this one.)
+
+- Have you ever lost hours getting everyone on your team to have the exact
+  same environment, but you're not willing to take the plunge and use a tool
+  like [nix](https://nixos.org)?
+
+- Are you frustrated by unclear documentation?  Is ramping up a frequent
+  problem?
+
+- Do you want a framework that's not only easy to write but also easy to get
+  inside and debug?
+
+- Have you been bogged down with details that are not relevant to the problems
+  you're trying to solve, the features you're trying to implement, the bugs
+  you're trying to fix?  We're talking authentication, authorization, XSS,
+  https, nested paths, all that stuff.
+
+## Getting started
+
+Different situations require different getting started docs.
+
+- [How to create a new project](docs/new-project.md)
+- [How to work on an existing project](docs/existing-project.md)
+
 ## Requirements
 
-To run diachron, you currently need the following requirements:
+To run diachron, you currently need to have a Linux box running x86_64 with a
+new enough libc to run golang binaries.  Support for other platforms will come
+eventually.
+
+To run a more complete system, you also need to have docker compose installed.
+
+### Development requirements
+
+To hack on diachron itself, you need the following:
 
 - docker compose
-- deno
-
-## Development requirements
-
-To hack on diachron, you need the following:
-
-- docker compose
-- deno
+- [fd](https://github.com/sharkdp/fd)
 - golang, version 1.23.6 or greater
+- shellcheck
+- shfmt
 
 

docs/deployment.md

@@ -0,0 +1 @@
+.

docs/new-project.md

@@ -0,0 +1,84 @@
+If any of the steps here don't work or are unclear in any way, it is
+probably a bug and we want to fix it!
+
+## how to create a new diachron project
+
+1. Create an empty directory for your project.  This directory can be inside of a
+   git repository but it doesn't have to be.
+
+2. Download the sync program and put it in the empty directory created in the
+   previous step.  There is a sync program for every version of diachron.
+   You'll usually want to use the most recent stable version.  [FIXME: explain
+   why you'd want to use something else.]  And you'll want the version for
+   the operating system and hardware you're using.
+
+3. Run the `setup` program.  This program is [FIXME: will be] written in
+   [go](https://go.dev), so as long as you have downloaded the right file, it
+   ought to work.
+   
+   This will create several files and directories.  It will also download a number
+   of binaries and put them in different places in some of the directories
+   that are created.
+
+4. At this point, you should have a usable, if not very useful, diachron
+   application.  To see what it does, run the program `develop run`; it will run a
+   simple web application on localhost:3000.  To make changes, have a look at
+   the files `src/app.ts` and `src/routes.ts`.
+
+## where do we go from here?
+
+Now that we have a very simple project, we need to attend to a few other
+important matters.
+
+### version control
+
+(These instructions assume you're using git.  If you're using a different
+version control system then you will need to make allowances.  In particular,
+you should convert the `.gitignore` file to whatever your version control
+system uses.)
+
+You should add the whole directory to git and commit it.  There will be two
+`.gitignore` files, one in the root, and one in the `framework/` directory.
+
+The root `.gitignore` created for you will be a good starting point, but you
+can make changes to it as you see fit.  However, you should not ever modify
+`framework/.gitignore`.  More on this in the next section.
+
+### working with diachron
+
+There are four commands to know about:
+
+- `sync` is used to install all dependencies, including the ones you specify
+  as well as the ones that diachron provides
+- `develop` is used to run "development-related" tasks.  Run `develop help` to
+  get an overview of what it can do.
+- `operate` is used to run "operations-related" tasks.  Run `operate help` to
+  get an overview of what it can do.
+- `cmd` runs diachron-managed commands, such as `pnpm`.  When working on a
+  diachron project, you should always use these diachron-managed commands
+  instead of whatever else you may have available.
+
+### what files belong to your project, what files belong to the framework
+
+In a new diachron project, there are some files and directories that are
+"owned" by the framework and others that are "owned" by the programmer.
+
+In particular, you own everything in the directory `src/`.  You own
+`README.md` and `package.json` and `pnpm-lock.yaml`.  You own any other files
+our directories you create.
+
+Everything else _belongs to the framework_ and you are not expected to change
+it except when upgrading.
+
+This is just an overview.  It is exhaustively documented in
+[ownership.md](ownership.md).
+
+### updates
+
+
+### when the docs sound a bit authoritarian...
+
+Finally, remember that diachron's license allows you to do whatever you like
+with it, with very few limitations.  This includes making changes to files
+about which, in the documentation, we say "you must not change" or "you are
+not expected to change."

docs/nomenclature.md

@@ -0,0 +1,4 @@
+We use `Call` and `Result` for our own types that wrap `Request` and
+`Response`.
+
+This hopefully will make things less confusing and avoid problems with shadowing.

docs/ownership.md

@@ -0,0 +1 @@
+.

docs/upgrades.md

@@ -0,0 +1 @@
+.