docs: refine README a bit and add mention of discovery
Change-Id: I6e8d55ccb04bed27c99523bade4a99b137c4f1f8
diff --git a/README.md b/README.md
index e271bf5..2a37a1c 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,42 @@
-Welcome to the Vanadium github repositories! Vanadium is an open source framework created by engineers at Google that is intended to make it much easier to develop secure, distributed applications that can run anywhere and everywhere. It provides:
+# Vanadium
-+ a complete security model, based on public-key cryptography, that supports fine
-grained permissioning and delegation. The combination of traditional ACLs and "blessings with caveats" supports a broad set of practical requirements.
-+ symmetrically authenticated and encrypted RPC. The RPC model is bi-directional, supports streaming and can be run through proxies. The result is a secure communications framework that can be used for large scale data-centre applications as well as for enterprise or consumer applications that need to navigate NAT boundaries.
-+ a self-describing encoding format that is both performant and designed to support a broad range of programming language semantics (today we have support for go, java and javascript).
-+ a global federated naming service that offers the convenience of urls but allows for federation and multilevel resolution. The 'programming model' consists of nothing more than invoking methods on names, subject to security constraints.
-+ the ability to use multiple global and/or local identity providers (e.g. Google, Facebook, Microsoft Exchange, pam etc). We currently provide an oauth2 based implementation but the others mentioned would work just as well.
-+ a storage service, Syncbase, that can be run on all devices, small or large, and offers synchronized peer-to-peer storage. Syncbase offers:
- - a structured store that can be queried using a sql-like language,
- - a blob store that synchronized content across all multiple devices,
- - the ability to group data into 'synchronization groups' to control which
- devices are synchronized,
- - fine grained access control,
- - peer-to-peer synchronization and conflict resolution,
- - offline operation is inherently supported.
+Welcome to the Vanadium GitHub repositories!
-We believe that the APIs should be well designed and stable and have taken pains to separate our APIs ([v.io/v23]) from all of our code that implements them. We provide a backwards compatibility guarantee for the APIs and have carried out usability testing on the APIs themselves.
+Vanadium is an open-source framework created by engineers at Google that makes
+it much easier to develop secure, distributed applications that can run
+anywhere. It provides:
++ a complete security model, based on public-key cryptography, that supports
+ fine-grained permissions and delegation. The combination of traditional ACLs
+ and "blessings with caveats" supports a broad set of practical requirements.
++ symmetrically authenticated and encrypted RPC, with support for bi-directional
+ messaging, streaming and proxying, that works on a variety of network
+ protocols, including TCP and Bluetooth. The result is a secure communications
+ infrastructure that can be used for large-scale datacenter applications as
+ well as for smaller-scale enterprise and consumer applications, including
+ those needing to cross NAT boundaries.
++ a performant, self-describing encoding format, usable from many programming
+ languages and platforms (including Go, Java/Android, and JavaScript, with more
+ on the way).
++ a global naming service that offers the convenience of urls but allows for
+ federation and multi-level resolution. The 'programming model' consists of
+ nothing more than invoking methods on names, subject to security checks.
++ a discovery API for advertising and scanning for services over a variety of
+ protocols, including BLE and mDNS (Bonjour).
++ the ability to use multiple global and/or local identity providers (e.g.
+ Google, Facebook, Microsoft Exchange, PAM, etc.). We currently provide an
+ OAuth2-based implementation, but others would work just as well.
++ a storage service, Syncbase, that can be run on all devices, large or small,
+ and offers synchronized peer-to-peer storage. Syncbase offers:
+ - a structured store that can be queried using a SQL-like query language
+ - a blob store that synchronizes content across all devices
+ - the ability to group data into 'synchronization groups' to control what's
+ synced with who
+ - fine-grained access control
+ - peer-to-peer synchronization with configurable conflict resolution
+ - offline operation
+
+The Vanadium APIs are relatively stable and have been subjected to extensive
+usability testing. In addition, we've taken care to cleanly separate the APIs
+([v.io/v23]) from their implementations.
[v.io/v23]: https://godoc.org/v.io/v23/
diff --git a/installation.md b/installation.md
index bd20598..919a0a6 100644
--- a/installation.md
+++ b/installation.md
@@ -15,7 +15,7 @@
On OS X, you'll also need the [Homebrew package manager][brew] installed. You
can install it with:
- # Mac-only prerequisite install
+ # Mac-only prerequisite.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
## JIRI_ROOT environment variable
