Add more clarity

docs/architecture-tags.md

@@ -6,7 +6,7 @@ permalink: architecture-tags.html
 summary:
 ---
 
-Tags can be added to Users, Comments and Assets.
+Tags are essentially strings that can be added to models. Currently, tags can be added to [Users, Comments and Assets](https://github.com/coralproject/talk/blob/ced449a1489d47c25d604020fa2e0b3b7a741353/graph/typeDefs.graphql#L144). If you would like to add tags to other models, you can extend this schema using [GraphQL hooks](plugins-server.html#graphql-hooks).
 
 ## Tag Definitions
 
@@ -53,12 +53,12 @@ This plugin allows users to self-report that their comment is "off topic" at the
 
 To accomplish this, the plugin creates the tag `OFF_TOPIC` with:
 
-* `public: true` - will be sent over the wire to the client side)
-* `self: true` - can be added by the active user to themselves or assets they own
-* `roles: []` - cannot be added by anyone based on their roles
+* `permissions.public: true` - will be sent over the wire to the client side
+* `permissions.self: true` - can be added by the active user to themselves or assets they own
+* `permissions.roles: []` - cannot be added by anyone based on their roles
 * `models: ['COMMENTS']` - can only be added to COMMENTS (not to users/assets/etc...)
 
-And viola! This tag is something that can only be created by the logged in user on their own comments and is sent over the wire to the client so it can display the badge.
+And [viola](https://youtu.be/Q0O9gFf-tiI?t=23s)! This tag is something that can only be created by the logged in user on their own comments and is sent over the wire to the client so it can display the badge.
 
 ## Tag Links
 
@@ -68,4 +68,4 @@ A TagLinks says that `tag` was `assigned_by` a specific user at a specific time
 
 Note that the `tag` field in the TagLinkSchema is the full TagSchema itself. This allows for another level of flexibility. Server code may generate Tags on the fly, complete with programmatically generated permissions and item behaviors.
 
-If a Tag definitions exists in the global/asset context then that definition will be used regardless of what is stored here. This allows high level controls on the behavior of tags.
+If a Tag definitions exists in the global/asset context then that definition will be used regardless of what is stored here. This allows high level controls on the behavior of tags, ensuring that plugins cannot produce unexpected definitions for already defined tags.

docs/architecture.md

@@ -6,13 +6,14 @@ permalink: architecture.html
 summary:
 ---
 
-## Talk's Plugin/Plugin API/Core Architecture
+## Talk's Architecture
 
-Talk consists of three distinct layers of code:
+Talk consists of four distinct layers of code:
 
 * Plugins
 * Plugin API
 * Core
+* cli
 
 ### Plugins
 
@@ -28,11 +29,15 @@ Talk core consists of architecture and functionality that deliver stability, sec
 
 Our goal is to continually extend our plugin infrastructure making the Core as pluggable as possible. Ultimately, a day may come where the Core of Talk is simply a framework for delivering a certain flavor of web applications.
 
+### cli
+
+Talk ships with a cli tool that exposes functionality to the command line. We seek to provide cli functionality for all features that could need to be accomplished programmatically or prior to the server's startup.
+
 ## Thinking about Plugins, the Plugin API and Core?
 
 The following is a template for a thought process that may help clarify your ideas against the backdrop of Talk's architecture.
 
-Think of a feature of capability. It could be something that's already in Talk or not. It could be something you want to build, or something you'd think would be a terrible idea. The important part here is to have something to interrogate.
+Think of a feature or capability. It could be something that's already in Talk or not. It could be something you want to build, or something you'd think would be a terrible idea. The important part here is to have something to interrogate.
 
 ```
 wait(60000);
@@ -60,7 +65,7 @@ Often times all the functionality a plugin needs is in the Core, but the Plugin
 
 Note: we are stabilizing the process by which new Plugin API bindings are created, agreed upon and ultimately made part of our Plugins Contract. If you are interested in this process, please reach out to us.
 
-### Does it need updates to the Plugin API _and_ Core?
+### Does it require updates to the Plugin API _and_ Core?
 
 What, if any, changes need to be made to Core so that the API can be extended?
 
@@ -72,4 +77,4 @@ We seek to keep Core as lean as possible.
 
 Amazing! We are always looking to extend the capabilities of Talk. We look forward to discussing what you've got to bring!
 
-Please see our [contributing guide](](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)) for more information about contributing Core code.
+Please see our [contributing guide](](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md)) for more information.