Update README.md

README.md

@@ -1,2 +1,59 @@
-# pico-package
+# PicoPackage
 
+*This project is very Alpha state and will change substantially.*
+
+This is a scheme for sharing code that's too small to be a language package ( Gem in Ruby, Package in Python, Create in Rust, Module in Perl or Go) but used frequently enough that copy and pasting between projects is painful. It is used to track a single file of code, allowing you to update it centrally for distribution. 
+
+Using the concept of `front matter` we add a commented section, as per the language requirements of the code, of metadata which will be parsed by the `ccp` tools. 
+
+# Hosting goals
+Ideally, code should be able to be hosted anywhere, but it'd be great to specifically support Github Gists.
+
+# Code Audience
+It's perfectly acceptable to use CCP for private code, for personal or organisational use.  It's perfectly acceptable for code for public consumption.
+
+# Dependency Management
+None - each file must be self contained.
+
+# Self Contained
+A file must be self contained, requiring / including any library to allow it to run
+
+# Testing
+Ideally, there'll be a test method or link to a test file.
+
+# Secure
+SHA hashes to ensure content hasn't changed. 
+SigStore to validate the author
+
+# Metadata
+Using comments, we'll include the following attributes
+
+## Required Metadata
+* source_url: Link to the latest version of this file. Links directly to the source ready for importing.
+* home_url: Link to the human readble version
+* version: the version of this file.
+* test_url: link to a related file for tests
+* test_method: name of the test method, if included within this file
+* licence: souce code licence
+* content_checksum: A sha256 hash of the file contents, excluding the front matter.
+
+## Optional Metadata
+* parent_revision: in the case of Gist style services, 
+* signature: A Base 64 Signature
+* public_key: The public key component for signature verification
+* sigstore: attributes for sigstore including :signature, :rekor_log_id, rekor_entry - for future 
+
+
+# Example
+```ruby
+# @META_START
+# home_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea$0
+# version: 1.0.0
+# source_url: https://gist.github.com/dkam/525ac4177964549ee2f2ca7febd03eea/raw/
+# test_method: test_me
+# licence: MIT
+# content_checksum: sha256:d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592
+# signature: base64:MEUCIQCjRx4RQvXxhPqvqyOB8FQtHGLuoA3pG4qBbNV4LGJTGAIgbZxXD9UFWqLsT+GZYs1DMqVXf6Lj2Dh8BM3wXJJ4Sxs=
+# public_key: -----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE7DxL6Mj/Bc9VhgKrWYItPqNxYPQ4\nzrVXXaHJWKNEHgSBgFH1AiJJ0cD3vFKkWuuhgnV8JdP/RXs4+G3oHqgQTA==\n-----END PUBLIC KEY-----
+# @META_END
+```