Update README.md

cmd/api/README.md

@@ -1,4 +1,14 @@
-First, be in a local directory containing buildpack-detectable source:
+## What is this?
+
+An experimental GCB API-compatible buildpack service running on Cloud Run. A GCB
+user can use any revently released `gcloud` along with this service to upload
+and build buildpack-compatible source and produce a container image.
+
+This is **an experiment** and should absolutely not be used for anything serious.
+
+## How do I use it?
+
+First, get into a local directory containing buildpack-detectable source:
 
 ```
 $ git clone git@github.com:buildpack/sample-java-app.git
@@ -53,14 +63,16 @@ statusDetail: ''
 
 - [ ] Builds are performed entirely in the context of the
   `projects.builds.create` request, not by polling a long-running operation.
+  The `--async` flag has no effect.
 - [ ] Build operations (source pulls and image pushes) are authorized using the
   end-user credentials, not the project's builder service account.
 - [ ] Build logs are not yet written to Cloud Storage, so they're not available
   via `gcloud`.
-- [ ] Timing is not collected or reported.
+- [ ] `timing` is not collected or reported.
 - [ ] `timeout` is not configurable. If Cloud Run request times out, client
   gets a 502.
-- [ ] `sourceProvenance` is not yet collected or reported.
+- [ ] `sourceProvenance` is not yet collected or reported, or uploaded to a
+  Grafeas instance.
 - [ ] `projects.builds.list` is not yet implemented.
 - [ ] `operations.get` and `operations.list` are not yet implemented.
 - [ ] `projects.builds.cancel` is not implementable (the client doesn't get the