update readme

CODE-OF-CONDUCT.md

+## ksonnet Community Code of Conduct
+
+### Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering
+an open and welcoming community, we pledge to respect all people who contribute
+through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for
+everyone, regardless of level of experience, gender, gender identity and expression,
+sexual orientation, disability, personal appearance, body size, race, ethnicity, age,
+religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic addresses,
+ without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are not
+aligned to this Code of Conduct. By adopting this Code of Conduct, project maintainers
+commit themselves to fairly and consistently applying these principles to every aspect
+of managing this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer(s).
+
+This Code of Conduct is adapted from the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md) and [Contributor Covenant](http://contributor-covenant.org/version/1/2/0/), version 1.2.0.

CONTRIBUTING.md

-## Managing vendor/
+## Contributing to ksonnet
 
-This project uses `govendor`.  To make things easier for reviewers,
-put updates to `vendor/` in a separate commit within the same PR.
+Thank you for taking the time to contribute to ksonnet! Before you submit any PRs, we encourage you to read the instructions for the [developer certificate of origin (DCO)](DCO-SIGNOFF.md), as well as the guidelines below:
 
-### Clean up removed/unnecessary dependencies
+* [Build](#build)
+* [Manage dependencies](#manage-dependencies)
+   * [Add a new dependency](#add-a-new-dependency)
+   * [Pin a dependency to a specific version](#pin-a-dependency-to-a-specific-version)
+   * [Clean up unnecessary dependencies](#clean-up-unnecessary-dependencies)
+* [Test](#test)
+* [Make a release](#make-a-release)
 
-This is a good one to run before sending a non-trivial change for
-review.
+### Build
 
+To build ksonnet locally (e.g. for open-source development), run the following in the root of your ksonnet repo:
 ```
-# See unused
-govendor list +unused
+make all
+```
+This indirectly makes the following targets:
+  * `make ks` - Compiles all the code into a `ks` binary
+  * `make docs` - Regenerates all the documentation for the ksonnet CLI, based on the code inside `cmd/`.
 
-# Remove unused
-govendor remove +unused
+*Troubleshooting*
+
+`make docs` relies on the `realpath` Linux utility. If you encounter a `realpath: command not found` error, and you are using OSX, run the following command:
+```
+brew install coreutils
 ```
+Running `make` again afterwards should work.
+
+### Manage dependencies
 
-### Add a new dependency
+This project uses `govendor` to manage Go dependencies. To make things easier for reviewers, put updates to `vendor/` in a separate commit within the same PR.
 
-Make code change that imports new library, then:
+#### Add a new dependency
+
+First make the code change that imports your new library, then run the following in the root of the repo:
 
 ```
-# See missing
+# View missing dependencies
 govendor list +missing
 
-% govendor fetch -v +missing
+# Download missing dependencies into vendor/
+govendor fetch -v +missing
 ```
 
-Note pinning a library to a specific version requires extra work.  In
-particular, we do this for `client-go` and `apimachinery` - to find
-the current version used for these libraries, look in
-`vendor/vendor.json` for the `version` field (not `versionExact`) of
-an existing package.  Use that same version in the commands below:
+#### Pin a dependency to a specific version
+
+Note that pinning a library to a specific version requires extra work.
+
+We do this for key libraries like `client-go` and `apimachinery`. To find the current version used for these particular packages, look in `vendor/vendor.json` for the `version` field (not `versionExact`).
 
+Use that same version in the commands below:
+
+```
+# Pin all imported client-go packages to release v3.0
+govendor fetch -v k8s.io/client-go/...@v3.0
 ```
-# For example: To pin all imported client-go packages to release v3.0
-% govendor fetch -v k8s.io/client-go/...@v3.0
 
-# *Note* the above may pull in new packages from client-go, which will
-# be imported at HEAD.  You need to re-run the above command until
-# all imports are at the desired version.
-# TODO: There is probably a better way to do this.
+*NOTE:* The command above may pull in new packages from `client-go`, which will
+be imported at HEAD.  You need to re-run the above command until *all* imports are at the desired version.
+
+If you make a mistake or miss some libraries, it is safe (and appropriate) to re-run `govendor fetch` with a different version.
+
+#### Clean up unnecessary dependencies
+
+Before sending a non-trivial change for review, consider running the following command:
+
+```
+# See unused dependencies
+govendor list +unused
+
+# Remove unused dependencies
+govendor remove +unused
 ```
 
-It is safe (and appropriate) to re-run `govendor fetch` with a
-different version, if you made a mistake or missed some libraries.
+### Test
+
+You can run ksonnet tests with `make test` in the root of the repo, specifying any additional, custom Go flags with `$EXTRA_GO_FLAGS`.
+
+### Make a Release
 
-## Making a Release
+To make a new release, follow these instructions:
 
-1. Add appropriate tag.  We do this via git (not github UI) so the tag
-   is signed.  This process requires you to have write access to the
-   real master branch (not your local fork).
+1. Add an appropriate tag.  We do this via `git` (not the github UI) so that the tag is signed.  This process requires you to have write access to the real `master` branch (not your local fork).
    ```
-   % tag=vX.Y.Z
-   % git fetch   # update
-   % git tag -s -m $tag $tag origin/master
-   % git push origin tag $tag
+   tag=vX.Y.Z
+   git fetch   # update
+   git tag -s -m $tag $tag origin/master
+   git push origin tag $tag
    ```
 
-2. Wait for the travis autobuilders to build release binaries.
+2. Wait for the Travis autobuilders to build release binaries.
 
-3. *Now* create the github release, using the existing tag created
+3. *Now* create the Github release, using the existing tag created
    above.

DCO-SIGNOFF.md

+## DCO Sign off
+
+All authors to the project retain copyright to their work. However, to ensure
+that they are only submitting work that they have rights to, we are requiring
+everyone to acknowledge this by signing their work.
+
+Any copyright notices in this repos should specify the authors as "The
+ksonnet authors".
+
+To sign your work, just add a line like this at the end of your commit message:
+
+```
+Signed-off-by: Joe Beda <joe@heptio.com>
+```
+
+This can easily be done with the `--signoff` option to `git commit`.
+
+By doing this you state that you can certify the following (from https://developercertificate.org/):
+
+```
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+1 Letterman Drive
+Suite D4700
+San Francisco, CA, 94129
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```

README.md

@@ -6,75 +6,169 @@
 *ksonnet* is a framework for writing, sharing, and deploying Kubernetes application manifests. With its CLI, you can generate a complete application from scratch in only a few commands, or manage a complex system at scale.
 
 Specifically, ksonnet allows you to:
-* *Reuse* common manifest patterns (within your app or from external libraries)
-* *Customize* manifests directly with powerful object concatenation syntax
-* *Deploy* app manifests to multiple environments
-* *Diff* across environments to compare two running versions of your app
-* *Track* the entire state of your app manifests in version control
+* **Reuse** common manifest patterns (within your app or from external libraries)
+* **Customize** manifests directly with powerful object concatenation syntax
+* **Deploy** app manifests to multiple environments
+* **Diff** across environments to compare two running versions of your app
+* **Track** the entire state of your app configuration in version controllable files
+
+All of this results in a more iterative process for developing manifests, one that can be supplemented by continuous integration (CI).
 
 *STATUS: Development is ongoing—this tool is pre-alpha.*
 
 ## Install
 
-To build from source:
+> You should have Go installed, and an appropriately set `$GOPATH`. (For most systems, the minimum Go version is 1.7. However, recent OSX may [require golang >=1.8.1](https://github.com/golang/go/issues/19734) to
+avoid an immediate `Killed: 9`.) If you need additional help, see the [official Go installation guide](https://golang.org/doc/install#install).
+
+ksonnet is installed like any other Go binary. Run the following shell commands to download ksonnet and ensure that it is runnable in any directory:
+
+```bash
+go get github.com/ksonnet/ksonnet
+PATH=$PATH:$GOPATH/bin
+```
+
+If your ksonnet is properly installed, you should be able to run the following `--help` command and see similar output:
 
-```console
-% PATH=$PATH:$GOPATH/bin
-% go get github.com/ksonnet/ksonnet
 ```
+$ ksonnet --help
+
+Synchronise Kubernetes resources with config files
 
-Requires golang >=1.7 and a functional cgo environment (C++ with libstdc++).
-Note that recent OSX environments
-[require golang >=1.8.1](https://github.com/golang/go/issues/19734) to
-avoid an immediate `Killed: 9`.
+Usage:
+  ks [command]
+
+Available Commands:
+  apply       Apply local configuration to remote cluster
+  delete      Delete Kubernetes resources described in local config
+  diff        Display differences between server and local config, or server and server config
+  env         Manage ksonnet environments
+  generate    Expand prototype, place in components/ directory of ksonnet app
+  ...
+```
 
 ## Quickstart
 
-```console
-# Include <ksonnet.git>/lib in ksonnet/jsonnet library search path.
-# Can also use explicit `-J` args everywhere.
-% export KUBECFG_JPATH=/path/to/ksonnet/lib
+Here we provide a shell script that shows some basic ksonnet features in action. You can run this script to deploy and update a basic web app UI, via a Kubernetes Service and Deployment. This app is shown below:
+
+<p align="center">
+<img alt="guestbook screenshot" src="/docs/img/guestbook.png" style="width:60% !important;">
+</p>
+
+Note that we will not be implementing the entire app in this quickstart, so the buttons will not work!
+
+**Minimal explanation is provided here, and only basic ksonnet features are shown---this is intended to be a quick demonstration.** If you are interested in learning more, see [Additional Documentation](#additional-documentation).
+
+### Prerequisites
+* *You should have access to an up-and-running Kubernetes cluster (**maximum version 1.7**).* Support for Kubernetes 1.8 is under development.
 
-# Show generated YAML
-% ks show -o yaml -f examples/guestbook.jsonnet
+  If you do not have a cluster, [choose a setup solution](https://kubernetes.io/docs/setup/) from the official Kubernetes docs.
 
-# Create resources
-% ks apply -f examples/guestbook.jsonnet
+* *You should have `kubectl` installed.* If not, follow the instructions for [installing via Homebrew (MacOS)](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos) or [building the binary (Linux)](https://kubernetes.io/docs/tasks/tools/install-kubectl/#tabset-1).
 
-# Modify configuration (downgrade gb-frontend image)
-% sed -i.bak '\,gcr.io/google-samples/gb-frontend,s/:v4/:v3/' examples/guestbook.jsonnet
-# See differences vs server
-% ks diff -f examples/guestbook.jsonnet
+* *Your `$KUBECONFIG` should specify a valid `kubeconfig` file*, which points at the cluster you want to use for this demonstration.
 
-# Update to new config
-% ks apply -f examples/guestbook.jsonnet
+### Script
+
+Copy and paste the script below to deploy the container image for a basic web app UI:
+
+```
+# Start by creating your app directory
+# (This references your current cluster using $KUBECONFIG)
+ksonnet init quickstart
+cd quickstart
+
+# Autogenerate a basic manifest
+ksonnet generate deployment-exposed-with-service guestbook-ui \
+--name guestbook \
+--image alpinejay/dns-single-redis-guestbook:0.3 \
+--type ClusterIP
+
+# Deploy your manifest to your cluster
+ksonnet apply default
+
+# Set up an API proxy so that you can access the guestbook service locally
+kc proxy > /dev/null &
+PROXY_PID=$!
+QUICKSTART_NAMESPACE=$(kubectl get svc guestbook -o jsonpath="{.metadata.namespace}")
+GUESTBOOK_SERVICE_URL=http://localhost:8001/api/v1/proxy/namespaces/$QUICKSTART_NAMESPACE/services/guestbook
+
+# Check out the guestbook app in your browser (NOTE: the buttons don't work!)
+open $GUESTBOOK_SERVICE_URL
+
+```
+
+The rest of this script upgrades the container image to a new version:
 
-# Clean up after demo
-% ks delete -f examples/guestbook.jsonnet
 ```
+# Bump the container image to a different version
+ksonnet param set guestbook-ui image alpinejay/dns-single-redis-guestbook:0.4
+
+# See the differences between your local manifest and what's running on your cluster
+# (ERROR is expected here since there are differences)
+ksonnet diff local:default remote:default
+
+# Update your cluster with your latest changes
+ksonnet apply default
+
+# (Wait a bit) and open another tab to see newly added javascript
+open $GUESTBOOK_SERVICE_URL
+
+```
+
+Notice that the webpage looks different! Now clean up:
+
+```
+# Teardown
+kill -9 $PROXY_PID
+ksonnet delete default
+
+# There should be no guestbook service left running
+kubectl get svc guestbook
+```
+
+Even though you've made modifications to the Guestbook app and removed it from your cluster, ksonnet still tracks all your manifests locally:
+
+```
+# View all expanded manifests (YAML)
+ks show default
+```
+
+If you're wondering how ksonnet differs from existing tools, the full-length tutorial (WIP) shows you how to use other ksonnet features to implement the rest of the Guestbook app (so that the buttons work!).
+
+## Additional documentation
+
+ksonnet is a feature-rich framework. To learn more about how to integrate it into your workflow, check out the resources below:
+
+* **Tutorial (WIP)** - How do I use ksonnet and why? This finishes the Guestbook app from the [Quickstart](#quickstart) above.
+
+* **Interactive tour of ksonnet (WIP)** - Where does the ksonnet magic come from?
+
+* **[CLI Reference](/docs/cli-reference#command-line-reference)** - What ksonnet commands are available, and how do I use them?
+
+* **[Concept Reference (WIP)](/docs/concepts.md)** - What do all these special ksonnet terms mean (e.g. *prototypes*) ?
+
+
+## Troubleshooting
+
+If you encounter any problems that the documentation does not address, [file an issue](https://github.com/ksonnet/ksonnet/issues).
+
+## Contributing
 
-## Features
+Thanks for taking the time to join our community and start contributing!
 
-- Supports JSON, YAML or jsonnet files (by file suffix).
-- Best-effort sorts objects before updating, so that dependencies are
-  pushed to the server before objects that refer to them.
-- Additional jsonnet builtin functions. See `lib/kubecfg.libsonnet`.
+#### Before you start
 
-## Infrastructure-as-code Philosophy
+* Please familiarize yourself with the [Code of
+Conduct](CODE_OF_CONDUCT.md) before contributing.
+* Read the contribution guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).
+* There is a [mailing list](https://groups.google.com/forum/#!forum/ksonnet) and [Slack channel](https://ksonnet.slack.com/) if you want to interact with
+other members of the community.
 
-The idea is to describe *as much as possible* about your configuration
-as files in version control (eg: git).
+#### Pull requests
 
-Changes to the configuration follow a regular review, approve, merge,
-etc code change workflow (github pull-requests, phabricator diffs,
-etc).  At any point, the config in version control captures the entire
-desired-state, so the system can be easily recreated in a QA cluster
-or to recover from disaster.
+* We welcome pull requests. Feel free to dig through the [issues](https://github.com/ksonnet/ksonnet/issues) and jump in.
 
-### Jsonnet
+## Changelog
 
-ksonnet relies heavily on [jsonnet](http://jsonnet.org/) to describe
-Kubernetes resources, and is really just a thin Kubernetes-specific
-wrapper around jsonnet evaluation.  You should read the jsonnet
-[tutorial](http://jsonnet.org/docs/tutorial.html), and skim the functions available in the jsonnet [`std`](http://jsonnet.org/docs/stdlib.html)
-library.
+See [the list of releases](https://github.com/ksonnet/ksonnet/releases) to find out about feature changes.

docs/README.md

+## Additional documentation
+
+While the ksonnet site updates are still pending, you can find additional documentation in this directory:
+
+* [CLI reference](/docs/cli-reference#command-line-reference)
+* [Concept reference](/docs/concepts.md)

docs/cli-reference/README.md

 # Command line reference
 
-Ksonnet provides a CLI (invoked with `ks`) that allows you to generate Kubernetes resource manifests locally (in `jsonnet`, `JSON`, or `YAML` format) and synchronize them with your remote cluster(s).
+Ksonnet provides a CLI (invoked with [`ks`](ks.md)) that allows you to generate Kubernetes resource manifests locally (in `jsonnet`) and synchronize them with your remote cluster(s).
 
 *The files in this directory enumerate each of the possible `ks` commands and their flags. Note that you can also find this info with the CLI itself, using the `--help` flag.*
+
+Suggested command usage is described below:
+
+## Getting started
+
+* Set up a ksonnet [*application*](/docs/concepts.md#application)
+  * [`ks init`](ks_init.md)
+
+* Generate [*components*](/docs/concepts.md#component) for your app (e.g. Redis)
+  * [`ks generate`](ks_generate.md) (alias of [`ks prototype use`](ks_prototype_use.md))
+
+* Deploy to a cluster
+  * [`ks apply`](ks_apply.md)
+
+* Delete resources running on a cluster
+  * [`ks delete`](ks_delete.md)  
+
+## Fancier components
+
+* Learn about existing [*prototypes*](/docs/concepts.md#prototype) ([`ks prototype`](ks_prototype.md))
+  * [`ks prototype list`](ks_prototype_list.md)
+  * [`ks prototype search`](ks_prototype_search.md)
+  * [`ks prototype describe`](ks_prototype_describe.md)
+  * [`ks prototype preview`](ks_prototype_preview.md)
+
+* Learn about and download currently available [*packages*](/docs/concepts.md#package) ([`ks pkg`](ks_pkg.md))
+  * [`ks pkg list`](ks_pkg_list.md)
+  * [`ks pkg describe`](ks_pkg_describe.md)
+  * [`ks pkg install`](ks_pkg_install.md)
+
+* Learn about existing [*registries*](/docs/concepts.md#registry) ([`ks registry`](ks_registry.md))
+  * [`ks registry list`](ks_registry_list.md)
+  * [`ks registry describe `](ks_registry_describe.md)
+
+## Environments
+
+* Managing [*environments*](/docs/concepts.md#environment) ([`ks env`](ks_env.md))
+  * [`ks env list`](ks_env_list.md)
+  * [`ks env add`](ks_env_add.md)
+  * [`ks env set`](ks_env_set.md)
+  * [`ks env rm`](ks_env_rm.md)
+
+* Customizing environments with [*parameters*](/docs/concepts.md#parameter) ([`ks param`](ks_param.md))
+  * [`ks param list`](ks_param_list.md)
+  * [`ks param set`](ks_param_set.md)
+
+* Comparing environments
+  * [`ks diff`](ks_diff.md)
+  * [`ks param diff`](ks_param_diff.md)
+
+## Miscellaneous
+
+* View expanded manifests
+  * [`ks show`](ks_show.md)
+
+* Validate manifests against the Kubernetes API
+  * [`ks validate`](ks_validate.md)
+
+* View metadata about the ksonnet binary
+  * [`ks version`](ks_version.md)

docs/concepts.md

+## Concepts
+
+The ksonnet framework is centered around a couple of key concepts.
+
+### Application
+TODO
+
+### Environment
+TODO
+
+### Component
+TODO
+
+### Prototype
+TODO
+
+### Parameter
+TODO
+
+### Part
+TODO
+
+### Package
+TODO
+
+### Registry
+TODO