feat(core): adds missing long manual output docs (#362)

Resolves #359

.github/spellcheck.ignore

@@ -8,23 +8,31 @@ CoolTool
 Decrypt
 ERS
 FQNs
+FQN
+FQN'd
 Hostname
 JSON
 JWT
 KASes
 KASs
 LDAP
 MacOS
+mapping's
 NPM
 Namespace
+namespace's
 Nano
 OIDC
 OpenTDF
+OpenID
 PDP
 PKCE
+plaintext
+pluggability
 README
 RadService
 SCS
+SCSs
 SDK
 ShinyThing
 TDF

docs/man/inspect/_index.md

@@ -4,3 +4,9 @@ command:
   name: inspect [file]
   flags:
 ---
+
+# Inspect a TDF file
+
+Prints the `manifest.json` of the specified TDF for inspection.
+
+This is useful for development and administration.

docs/man/policy/_index.md

@@ -12,7 +12,7 @@ command:
       default: 'false'
 ---
 
-Manage policies within the platform.
+# Manage platform policy
 
 Policy is a set of rules that are enforced by the platform. Specific to the the data-centric
 security, policy revolves around data attributes (referred to as attributes). Within the context

docs/man/policy/attributes/_index.md

@@ -7,6 +7,8 @@ command:
     - attribute
 ---
 
+# Manage attributes
+
 Commands to manage attributes within the platform.
 
 Attributes are used to to define the properties of a piece of data. These attributes will then be

docs/man/policy/attributes/create.md

@@ -32,3 +32,26 @@ command:
       shorthand: l
       default: ''
 ---
+
+# Create an attribute definition
+
+Under a namespace, create an attribute with a rule.
+
+### Rules
+
+#### ANY_OF
+
+If an Attribute is defined with logical rule `ANY_OF`, an Entity who is mapped to `any` of the associated Values of the Attribute
+on TDF'd Resource Data will be Entitled.
+
+#### ALL_OF
+
+If an Attribute is defined with logical rule `ALL_OF`, an Entity must be mapped to `all` of the associated Values of the Attribute
+on TDF'd Resource Data to be Entitled.
+
+### HIERARCHY
+
+If an Attribute is defined with logical rule `HIERARCHY`, an Entity must be mapped to the same level Value or a level above in hierarchy
+compared to a given Value on TDF'd Resource Data. Hierarchical values are considered highest at index 0 and lowest at the last index.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/deactivate.md

@@ -8,3 +8,14 @@ command:
       description: ID of the attribute
       required: true
 ---
+
+# Deactivate an attribute definition
+
+Deactivation preserves uniqueness of the attribute and values underneath within policy and all existing relations,
+essentially reserving them.
+
+However, a deactivation of an attribute means its associated values cannot be entitled in an access decision.
+
+For information about reactivation, see the `unsafe reactivate` subcommand.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/get.md

@@ -9,3 +9,9 @@ command:
       shorthand: i
       description: ID of the attribute
 ---
+
+# Get an attribute
+
+Retrieve an attribute along with its metadata, rule, and values.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/list.md

@@ -14,3 +14,9 @@ command:
         - any
       default: active
 ---
+
+# List the known attributes
+
+By default, the list will only provide `active` attributes if unspecified, but the filter can be controlled with the `--state` flag.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/namespaces/_index.md

@@ -1,10 +1,20 @@
 ---
 title: Manage attribute namespaces
-command: 
+command:
   name: namespaces
   aliases:
     - ns
     - namespace
 ---
 
 # Manage attribute namespaces
+
+A namespace is the root (parent) of a set of platform policy. Like an owner or an authority, it fully qualifies attributes and their values,
+resource mapping groups, etc. As the various mappings of a platform are to attributes or values, a namespace effectively "owns" the
+mappings as well (transitively if not directly).
+
+In an attribute or other FQN (Fully Qualified Name), the namespace is found after the scheme: `https://<namespace>`
+
+Namespaces, like other FQN'd objects, are normalized to lower case both on create and in a decision request lookup.
+
+As the Namespace is the parent of policy, a namespace's existence is required to create attributes or resource mapping groups beneath.

docs/man/policy/attributes/namespaces/create.md

@@ -14,5 +14,11 @@ command:
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
 ---
+
+# Create an attribute namespace
+
+Creation of a `namespace` is required to add attributes or any other policy objects beneath.
+
+For more information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/deactivate.md

@@ -11,11 +11,15 @@ command:
       description: Force deletion without interactive confirmation (dangerous)
 ---
 
+# Deactivate an attribute namespace
+
 Deactivating an Attribute Namespace will make the namespace name inactive as well as any attribute definitions and values beneath.
 
 Deactivation of a Namespace renders any existing TDFs of those attributes inaccessible.
 
 Deactivation will permanently reserve the Namespace name within a platform. Reactivation and deletion are both considered "unsafe"
 behaviors.
 
+For information about reactivation, see the `unsafe reactivate` subcommand.
+
 For reactivation, see the `unsafe` command.

docs/man/policy/attributes/namespaces/get.md

@@ -11,3 +11,4 @@ command:
 ---
 
 # Get an attribute namespace
+

docs/man/policy/attributes/namespaces/list.md

@@ -12,3 +12,5 @@ command:
 ---
 
 # List attribute namespaces
+
+For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/unsafe/_index.md

@@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might
 accessible or vice versa.
 
 Make sure you know what you are doing.
+
+For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/unsafe/delete.md

@@ -16,3 +16,5 @@ Deleting a Namespace cascades deletion of any Attribute Definitions, Values, and
 Any existing TDFs containing attributes under this namespace will be rendered inaccessible until it has been recreated.
 
 Make sure you know what you are doing.
+
+For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/unsafe/reactivate.md

@@ -16,3 +16,5 @@ Reactivating a Namespace can potentially open up an access path to any existing
 The Active/Inactive state of any Attribute Definitions or Values under this Namespace will NOT be changed.
 
 Make sure you know what you are doing.
+
+For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/unsafe/update.md

@@ -21,3 +21,5 @@ Any existing TDFs containing attributes under the old namespace will be rendered
 and already created may now become accessible.
 
 Make sure you know what you are doing.
+
+For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/namespaces/update.md

@@ -12,14 +12,14 @@ command:
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
     - name: force-replace-labels
       description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
       default: false
 ---
 
 # Update an Attribute Namespace
 
-Attribute Namespace changes can be dangerous, so this command is for updates considered "safe."
+Attribute Namespace changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
 
-For unsafe updates, see the dedicated `update` command.
+For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `namespaces` subcommand.

docs/man/policy/attributes/unsafe/_index.md

@@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might
 accessible or vice versa.
 
 Make sure you know what you are doing.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/unsafe/delete.md

@@ -16,3 +16,5 @@ Deleting an Attribute Definition cascades deletion of any Attribute Values and a
 Any existing TDFs containing the deleted attribute of this name will be rendered inaccessible until it has been recreated.
 
 Make sure you know what you are doing.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/unsafe/reactivate.md

@@ -16,3 +16,5 @@ Reactivating an Attribute Definition can potentially open up an access path to a
 The Active/Inactive state of any Attribute Values under this Definition will NOT be changed.
 
 Make sure you know what you are doing.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/unsafe/update.md

@@ -46,3 +46,5 @@ To remove Values from an Attribute Definition, delete them separately via the `v
 `values create` commands.
 
 Make sure you know what you are doing.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/update.md

@@ -17,3 +17,11 @@ command:
       description: Destructively replace entire set of existing metadata 'labels' with any provided to this command
       default: false
 ---
+
+# Update an attribute
+
+Attribute Definition changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
+
+For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `attributes` subcommand.
+
+For more general information about attributes, see the `attributes` subcommand.

docs/man/policy/attributes/values/_index.md

@@ -7,4 +7,25 @@ command:
     - value
 ---
 
-This command allows you to manage the values of an attribute.
+# Manage attribute values 
+
+Attribute values are the individual units tagged on TDFs containing Resource Data.
+
+They are mapped to entitle person and non-person entities through Subject Mappings, to varied terms for tagging providers
+through Resource Mappings, to individual keys and Key Access Servers through KAS Grants, and more.
+
+They are fully-qualified through the FQN structure `https://<namespace>/attr/<definition name>/value/<value>`, and the presence
+of one or more values on a piece of Resource Data (a TDF) determines an entity's access to the data through a combination
+of entitlements and the attribute definition rule evaluation.
+
+In other words, Attribute Values are the atomic units that drive access control relation of Data -> Entities and vice versa.
+
+Values are contextualized by Attribute Definitions within Namespaces, and only have logical meaning as part of a Definition.
+
+Giving data multiple Attribute Values across the same or multiple Definitions/Namespaces will require all of the definition rules to be satisfied
+by an Entity's mapped Entitlements to result in key release, decryption, and resulting access to TDF'd data.
+
+For more information on:
+- values, see the `attributes values` subcommand
+- attribute definitions, see the `attributes` subcommand
+- namespaces, see the `attributes namespaces` subcommand

docs/man/policy/attributes/values/create.md

@@ -16,7 +16,13 @@ command:
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
-      default: ""
+      default: ''
 ---
 
-This command allows you to manage the values of an attribute.
+# Create an attribute value
+
+Add a single new value underneath an existing attribute.
+
+For a hierarchical attribute, a new value is added in lowest hierarchy (last).
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/deactivate.md

@@ -7,3 +7,13 @@ command:
       shorthand: i
       description: The ID of the attribute value to deactivate
 ---
+
+# Deactivate an attribute value
+
+Deactivation preserves uniqueness of the attribute value within policy and all existing relations, essentially reserving it.
+
+However, a deactivation of an attribute value means it cannot be entitled in an access decision.
+
+For information about reactivation, see the `unsafe reactivate` subcommand.
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/get.md

@@ -9,3 +9,9 @@ command:
       shorthand: i
       description: The ID of the attribute value to get
 ---
+
+# Get an attribute value
+
+Retrieve an attribute value along with its metadata.
+
+For more general information about attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/list.md

@@ -20,3 +20,7 @@ command:
 ---
 
 # List attribute values
+
+By default, the list will only provide `active` values if unspecified, but the filter can be controlled with the `--state` flag.
+
+For more general information about attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/unsafe/_index.md

@@ -17,3 +17,5 @@ Depending on the unsafe change introduced and already existing TDFs, TDFs might
 accessible or vice versa.
 
 Make sure you know what you are doing.
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/unsafe/delete.md

@@ -16,3 +16,5 @@ Deleting an Attribute Value cascades deletion of any associated mappings underne
 Any existing TDFs containing the deleted attribute of this value will be rendered inaccessible until it has been recreated.
 
 Make sure you know what you are doing.
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/unsafe/reactivate.md

@@ -16,3 +16,5 @@ Reactivating an Attribute Value can potentially open up an access path to any ex
 The Active/Inactive state of the Attribute Definition and Namespace above this Value will NOT be changed.
 
 Make sure you know what you are doing.
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/unsafe/update.md

@@ -22,3 +22,5 @@ Any existing TDFs containing attributes under the old value will be rendered ina
 and already created may now become accessible.
 
 Make sure you know what you are doing.
+
+For more information on attribute values, see the `values` subcommand.

docs/man/policy/attributes/values/update.md

@@ -9,9 +9,6 @@ command:
     - name: id
       shorthand: i
       description: The ID of the attribute value to update
-    - name: value
-      shorthand: v
-      description: The new value
     - name: label
       description: "Optional metadata 'labels' in the format: key=value"
       shorthand: l
@@ -21,4 +18,10 @@ command:
       default: false
 ---
 
-This command allows you to manage the values of an attribute.
+# Update an attribute value
+
+Attribute Value changes can be dangerous, so this command is for updates considered "safe" (currently just mutations to metadata `labels`).
+
+For unsafe updates, see the dedicated `unsafe update` command. For more general information, see the `values` subcommand.
+
+For more general information about attributes, see the `attributes` subcommand.